Offrire supporto tramite SMS ai chiamanti usando il widget Squilla tramite API

I lunghi tempi di attesa sono uno dei modi più rapidi per frustrare chi chiama. Invece di lasciare i clienti in attesa in coda o respingerli quando tutti gli agenti sono occupati, puoi usare il tuo IVR per offrire loro supporto tramite SMS. Quando chi chiama sceglie questa opzione, Aircall invia un messaggio di testo da uno dei tuoi numeri abilitati agli SMS. Chi chiama risponde quando preferisce e la conversazione arriva nella posta in arrivo Aircall dei tuoi agenti, dove viene gestita come qualsiasi altra conversazione SMS.

Questa soluzione è utile in due situazioni comuni:

• Scelta proattiva: offri subito gli SMS, così chi preferisce i messaggi non dovrà mai attendere in linea.
• Overflow, tutti gli agenti occupati: quando nessun agente è disponibile, offri gli SMS come modo per ricevere comunque assistenza, anziché limitarsi ad attendere in coda o riagganciare.

Poiché gli SMS raggiungono solo chi chiama dai Paesi coperti dal tuo numero mittente, questa soluzione funziona meglio quando chi chiama e i tuoi numeri si trovano nello stesso mercato. Per offrire la messaggistica a chi chiama da qualsiasi luogo, puoi anche proporre WhatsApp nella stessa diramazione: un solo numero abilitato a WhatsApp raggiunge chiunque utilizzi l'app, indipendentemente dal Paese. Consulta Offrire supporto tramite WhatsApp a chi chiama usando il widget Ring to via API.

Nota: Questa configurazione richiede la creazione di una richiesta API all'interno di un flusso di chiamata, incluso un corpo JSON e l'autenticazione Basic. Non è necessario essere sviluppatori, ma occorre saper seguire istruzioni tecniche dettagliate e sequenziali.

Come funziona

1. Un cliente chiama il tuo numero Aircall ed entra nel tuo flusso di chiamata.
2. Chi chiama raggiunge un punto in cui vengono offerti gli SMS, come opzione di menu ("Premi 1 per ricevere assistenza tramite messaggio di testo anziché attendere") oppure come diramazione di overflow che si attiva quando nessun agente è disponibile.
3. In tale diramazione, il widget Ring to via API invia una richiesta all'endpoint di messaggistica di Aircall, specificando il numero abilitato agli SMS da usare come mittente, il testo da inviare e il numero destinatario, ovvero quello di chi chiama.
4. Chi chiama riceve l'SMS e può rispondere. La risposta arriva nella stessa conversazione nella posta in arrivo di Aircall ed è visibile ai tuoi agenti.
5. La chiamata termina con una breve conferma vocale.

Importante: Il widget Ring to via API invia la richiesta, ma non può diramare la chiamata in base alla risposta dell'API. Tutto ciò che segue il widget, come un messaggio di conferma, la conclusione della chiamata o un percorso alternativo, deve verificarsi indipendentemente dall'effettivo invio del messaggio.

Prima di iniziare

Prima di iniziare, assicurati che siano già soddisfatti i seguenti requisiti:

• Piano: utilizzi il piano Aircall Professional. Sia il widget Ring to via API sia l'accesso diretto alla Messaging API sono funzionalità Professional; i piani Custom includono tutto ciò che è compreso in Professional. Per eseguire l'upgrade, contatta il responsabile del tuo Il mio conto Aircall.
• Accesso: disponi dell'accesso come amministratore al Dashboard Aircall e all'editor del flusso di chiamata.
• Un numero mittente abilitato agli SMS: il numero da cui viene inviato il messaggio deve essere abilitato agli SMS nel tuo Il mio conto.

Gli ID e le credenziali specifici necessari, ovvero ID del numero, ID della chiave API e token, vengono recuperati nei passaggi 1 e 2 qui sotto, quindi non occorre procurarseli in anticipo. Per informazioni generali sul funzionamento dell'API di Aircall, consulta Aircall per sviluppatori: riferimenti API. Per informazioni specifiche sulla messaggistica, consulta Messaging API di Aircall e Panoramica degli SMS per sviluppatori.

Passaggio 1: scegli il numero da cui viene inviato l'SMS

Il messaggio viene inviato da uno dei tuoi numeri Aircall e tale numero determina dove viene archiviata la conversazione. Sceglilo prima di configurare qualsiasi elemento.

Passaggi

1. Verifica che il numero sia abilitato agli SMS. Consulta SMS (messaggistica di testo aziendale) per verificare l'idoneità in base al Paese e al tipo di numero.
2. Verifica chi deve vedere le risposte. Ogni agente assegnato a quel numero vede la conversazione e può rispondere dalla propria App Aircall, quindi scegli un numero già gestito dal team appropriato.
3. Decidi se riutilizzare il numero chiamato. L'esecuzione di un flusso di chiamata non impedisce a un numero di inviare SMS, quindi il numero chiamato può fungere anche da mittente, purché sia abilitato agli SMS. Molti numeri vocali non lo sono, quindi la scelta predefinita più sicura consiste nell'inserire direttamente un numero che sai essere abilitato agli SMS.

Nota: Facoltativamente, la richiesta può indicare un agente specifico tramite il campo agentId, attribuendo così il messaggio in uscita a tale utente. L'utente deve essere assegnato al numero mittente, altrimenti la richiesta viene rifiutata. Se ometti il campo, il messaggio viene attribuito a "strumento esterno" in Aircall Workspace.

Passaggio 2: recupera l'ID del numero e le credenziali API

Per la richiesta servono due elementi, entrambi recuperati al di fuori dell'editor del flusso di chiamata.

ID API e token API

Vai su Dashboard Aircall > Integrazioni > Chiavi API e fai clic su Genera chiave API. Inserisci un nome per la chiave, quindi copia l'ID API e il token API prima di chiudere la finestra: il token non verrà mostrato di nuovo. Queste sono le credenziali usate dal widget per l'autenticazione. Per maggiori dettagli, consulta Ottenere la chiave API di Aircall.

ID del numero

È l'ID del numero abilitato agli SMS da cui viene inviato il messaggio. Esistono due modi per recuperarlo:

• Dall'URL del Dashboard (metodo più rapido): apri Numeri, seleziona il numero e leggi l'ID nella barra degli indirizzi. In https://dashboard.aircall.io/numbers/1186183/call-distribution, l'ID del numero è 1186183.
• Dall'API: chiama l'endpoint Elenca tutti i numeri; ogni numero nella risposta dispone di un id.

In entrambi i casi, questo è il valore da inserire nell'URL della richiesta.

Importante: L'ID del numero va inserito nel percorso URL della richiesta, non nel corpo della richiesta.

Passaggio 3: crea il flusso di chiamata nell'editor di flussi

Passaggi

1. Vai a Dashboard Aircall > Numeri > Numeri.
2. Seleziona il numero e fai clic sul pulsante verde Modifica per aprire l'editor di flussi.
3. Decidi dove offrire gli SMS:

   • Come opzione del menu: aggiungi un widget del menu IVR, ad esempio: "Per continuare tramite SMS anziché attendere, premi 1. Per rimanere in linea, premi 2."

     

   • Come overflow: posiziona il widget Chiama tramite API sul ramo raggiunto quando nessun agente è disponibile.

     

Passaggio 4: configura il widget Chiama tramite API

Aggiungi il widget Chiama tramite API sul ramo degli SMS e configura la richiesta come segue. Questa richiesta utilizza l'endpoint Invia messaggio nella conversazione dell'agente, che rende la conversazione visibile agli agenti.

Autenticazione

L'endpoint utilizza l'autenticazione HTTP Basic. Nelle impostazioni di autenticazione del widget, scegli Basic e inserisci:

• Nome utente: il tuo ID API

• Password: il tuo token API

  

Il widget crea automaticamente l'autorizzazione, senza necessità di codifica manuale.

Configurazione della richiesta

• Metodo: POST
• URL: https://api.aircall.io/v1/numbers/1018591/messages/native/send, sostituisci 1018591 con l'ID del tuo numero ottenuto nel passaggio 2.

Corpo della richiesta:

{
  "to": "{{callerNumber}}",
  "body": "Thanks for calling! Reply to this text and an agent will help you shortly."
}

Corpo della richiesta, attribuito a un agente specifico (facoltativo):

{
  "to": "{{callerNumber}}",
  "body": "Thanks for calling! Reply here and an agent will pick this up shortly.",
  "agentId": 456789
}

Riferimento dei campi:

• to (obbligatorio): il numero a cui viene inviato l'SMS. Usa il formato E.164, con un + e il prefisso internazionale. Usa {{callerNumber}} affinché l'editor di flussi inserisca il numero del chiamante durante l'esecuzione; la variabile viene già risolta nel formato E.164.
• body (obbligatorio): il testo da inviare, fino a 1.600 caratteri. I messaggi più lunghi vengono rifiutati.
• agentId (facoltativo, numero intero): l'ID dell'utente Aircall a cui deve essere attribuito il messaggio. L'utente deve essere assegnato al numero mittente.
• L'ID del numero non è un campo del corpo, ma il segmento :id dell'URL.

Variabili del flusso di chiamata utilizzabili nell'URL o nel corpo: {{callerNumber}}, {{targetNumber}}, {{callUUID}} e {{lineId}}. Se il flusso contiene un widget Input IVR, l'input acquisito è disponibile come variabile aggiuntiva con lo stesso nome del widget. La sostituzione funziona sia nell'URL sia nel corpo della richiesta.

L'inserimento diretto dell'ID del numero mittente nell'URL, come indicato sopra, è l'approccio più chiaro. In alternativa, puoi usare {{lineId}}, che viene risolto nel numero composto dal chiamante, ma solo se tale numero supporta gli SMS.

Importante: {{callerNumber}} invia l'SMS al numero da cui sta chiamando il chiamante. Se tale numero non può ricevere SMS, è un numero di rete fissa o è un numero internazionale non incluso tra le destinazioni consentite per il tuo numero, la consegna non riuscirà. Tienilo presente quando decidi se offrire l'opzione SMS a ogni chiamante.

Configurazione della risposta

Il widget richiede una configurazione della risposta prima di poter pubblicare il flusso, anche se questo flusso non esegue l'instradamento in base alla risposta (la chiamata viene chiusa nel passaggio successivo indipendentemente dal risultato). Compila questi campi con un segnaposto che intenzionalmente non viene risolto:

• Tipo di risposta: numero Aircall (interno)
• Percorso: null

L'SMS viene inviato prima che il widget esamini la risposta, quindi il messaggio viene comunque trasmesso. Poiché il percorso non viene mai risolto, il widget considera la risposta non valida e passa semplicemente al passaggio successivo del flusso, come previsto in questo caso.

Nota: Tutti gli endpoint API pubblici di Aircall condividono un limite di 120 richieste al minuto. Ogni numero ha inoltre i propri limiti orari, giornalieri e mensili per i messaggi, che vengono azzerati in base all'UTC e sono condivisi con l'endpoint skipping-inbox (numeri long code e numeri verdi di Stati Uniti e Canada: 5.000 / 10.000 / 100.000; numeri della piattaforma del Regno Unito, australiani, tedeschi, spagnoli e francesi: 500 / 2.000 / 20.000; numeri di cellulare francesi: 100 / 1.000 / 10.000). Ciò non dovrebbe influire su un normale flusso di chiamata, ma è utile saperlo se esegui test su larga scala. Le richieste del widget scadono dopo 10 secondi e non vengono ripetute.

Passaggio 5: chiudi il flusso di chiamata

Poiché il widget non può reagire alla risposta dell'API, termina correttamente il ramo indipendentemente dal risultato.

Passaggi

1. Dopo il widget, fai clic su + e aggiungi un Messaggio audio, ad esempio: "Ti abbiamo appena inviato un SMS. Puoi rispondere quando vuoi. Grazie."
2. Termina la chiamata oppure, come opzione di riserva, instradala alla segreteria telefonica o a un altro team.

Nota: L'editor di flussi mostra in grigio i passaggi successivi al widget Ring to via API, perché presuppone che la chiamata lasci il flusso per far squillare un destinatario. In questa configurazione, la chiamata non lascia il flusso, quindi tali passaggi vengono eseguiti. La visualizzazione in grigio è un'anomalia nota e può essere ignorata senza problemi.

Passaggio 6: prova il flusso

Prova prima la richiesta all'interno del widget, quindi effettua una chiamata reale quando funziona.

Prova dal widget

Il widget può simulare un chiamante, quindi non è necessario pubblicare il flusso o chiamare il numero per verificare che l'SMS venga inviato.

Passaggi

1. Nel widget, individua il campo Prova richiesta e inserisci un payload che indichi il numero da simulare:

{
  "callerNumber": "+15551234567"
}

2. Fai clic su Prova richiesta. Il widget si comporta come se quel numero avesse chiamato e raggiunto questo punto del flusso, quindi l'SMS viene effettivamente inviato: usa un numero che puoi controllare.
3. Verifica che il messaggio arrivi e che la conversazione compaia nella posta in arrivo di Aircall.

Nota: La prova segnalerà un errore anche quando il messaggio viene inviato correttamente. È previsto: la configurazione della risposta punta intenzionalmente a un percorso che non viene mai risolto, quindi il widget considera la risposta non valida. Ignora l'errore e verifica invece il risultato sul telefono e nella posta in arrivo.

Prova l'intero flusso

Passaggi

1. Fai clic su Pubblica nell'angolo in alto a destra.
2. Chiama il numero da un telefono cellulare in grado di ricevere SMS.
3. Raggiungi il ramo SMS (seleziona l'opzione oppure attiva la condizione di overflow).
4. Verifica di ricevere il messaggio, che il testo sia corretto, che venga riprodotta la conferma vocale e che una risposta apra o continui una conversazione nella posta in arrivo di Aircall.

Se il messaggio non arriva, consulta la tabella di risoluzione dei problemi riportata di seguito.

Risoluzione dei problemi

L'elenco completo dei codici di risposta per questo endpoint è disponibile nella documentazione di riferimento dell'API.

FAQ

I miei agenti vedranno la conversazione SMS se il chiamante risponde?

Sì. Questa richiesta utilizza l'endpoint Invia messaggio nella conversazione dell'agente, quindi sia il messaggio in uscita sia la risposta del cliente compaiono nella posta in arrivo di Aircall per ogni agente che gestisce il numero mittente e negli eventi del Webhook dei messaggi.

È necessario un modello approvato per il messaggio?

No. Il testo è in formato libero, viene scritto direttamente nel corpo della richiesta e può contenere fino a 1.600 caratteri. Non è necessario far approvare alcun modello e non vi sono finestre temporali per la messaggistica da rispettare.

E per i chiamanti di altri Paesi?

Gli SMS tramite API sono disponibili solo a livello nazionale, fatta eccezione per Stati Uniti e Canada, quindi è possibile inviare un messaggio a un chiamante solo da un numero che copre il suo Paese. Se i chiamanti si trovano in Paesi diversi, aggiungi un numero locale abilitato per gli SMS per ciascun mercato oppure offri la messaggistica tramite WhatsApp sullo stesso ramo. WhatsApp non è vincolato al Paese del chiamante, quindi un solo numero abilitato per WhatsApp consente di raggiungere chiunque utilizzi l'app. Consulta Offrire Supporto tramite WhatsApp ai chiamanti usando il widget Ring to via API.

Posso inviare un'immagine o un PDF?

No. Gli MMS non sono supportati su questo endpoint. Se devi inviare contenuti multimediali, usa l'endpoint Invia messaggio ignorando la posta in arrivo di Aircall, ma questi messaggi non compaiono nell'App Aircall, quindi gli agenti non possono proseguire la conversazione.

Posso inviare dal numero chiamato dal chiamante?

Sì, purché quel numero sia abilitato per gli SMS e non sia configurato per la messaggistica che ignora la posta in arrivo. L'esecuzione di un flusso di chiamata, incluso uno con un menu IVR, non impedisce a un numero di inviare SMS. In pratica, molti numeri vocali non sono abilitati per gli SMS, per questo l'articolo inserisce direttamente un numero noto abilitato per gli SMS. Se il numero chiamato è abilitato per gli SMS, puoi usare {{lineId}} nell'URL.

Posso personalizzare il messaggio con i dati del chiamante?

Sì, nei limiti di quanto reso disponibile dall'editor del flusso di chiamata. Puoi inserire {{callerNumber}}, {{targetNumber}}, {{callUUID}} o {{lineId}} nel corpo del testo, oltre a qualsiasi input acquisito in precedenza nel flusso da un widget Input IVR. Per dati più dettagliati, ad esempio un nome proveniente dal CRM, sarebbe necessario un livello middleware che cerchi il chiamante ed effettui autonomamente la chiamata all'API Aircall.

Cosa succede se il numero del chiamante non può ricevere SMS?

La consegna non riesce e il widget non può avvisare il chiamante. Poiché il messaggio viene inviato al numero da cui il chiamante ha effettuato la chiamata, mantieni sempre un'opzione alternativa comunicata a voce e un percorso verso una coda o la segreteria telefonica in quel ramo.