Offrire supporto tramite WhatsApp ai chiamanti usando il widget Chiama tramite API

I lunghi tempi di attesa sono uno dei modi più rapidi per irritare chi chiama. Invece di lasciare i clienti in coda o respingerli quando tutti gli agenti sono occupati, puoi usare il tuo IVR per offrire loro supporto tramite WhatsApp. Quando chi chiama sceglie questa opzione, Aircall invia al suo numero un modello WhatsApp approvato. La persona risponde quando preferisce e la conversazione arriva nella Posta in arrivo di Aircall degli agenti, dove viene gestita come qualsiasi altra conversazione WhatsApp.

Questa funzione è utile in due situazioni comuni:

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

Nota: Questa configurazione richiede la creazione di una richiesta API all'interno di un flusso di chiamata, inclusi un corpo JSON e l'autenticazione di base. Non devi essere uno sviluppatore, ma dovresti avere dimestichezza con istruzioni tecniche dettagliate.

Come funziona

1. Un cliente chiama il tuo numero Aircall ed entra nel tuo Creare un semplice IVR di supporto in un flusso di chiamata
2. Chi chiama raggiunge un punto in cui viene proposto WhatsApp, come opzione del menu ("Premi 1 per ricevere assistenza su WhatsApp anziché attendere") oppure come ramo di overflow che si attiva quando nessun agente è disponibile.
3. In quel ramo, il widget Inoltra tramite API invia una richiesta all'endpoint di messaggistica WhatsApp di Aircall, specificando la linea da cui inviare il messaggio, il modello da usare e il numero a cui inviarlo, ovvero quello di chi chiama.
4. Chi chiama riceve il messaggio WhatsApp e può rispondere. La risposta apre una conversazione nella Posta in arrivo di Aircall, visibile agli agenti.
5. La chiamata termina con una breve conferma vocale.

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

Prima di iniziare

Prima di iniziare, assicurati che siano già soddisfatte le seguenti condizioni:

• Hai un piano Aircall Professionale o Personalizzato. Il widget Inoltra tramite API non è disponibile con altri piani.
• Hai l'accesso come amministratore al Dashboard Aircall e all'editor di flussi.
• Nel tuo Il mio conto è presente un numero compatibile con WhatsApp per il quale è abilitata la messaggistica WhatsApp.
• Hai, o puoi creare, un modello WhatsApp già approvato da WhatsApp/Meta.

Nota: I messaggi WhatsApp avviati dall'azienda richiedono sempre un modello approvato. I messaggi in formato libero sono possibili solo entro una finestra aperta di 24 ore, dopo che il cliente ti ha contattato per primo. Se offri questa opzione a chiunque chiami, consulta anche i requisiti di WhatsApp relativi all'adesione e alla revoca del consenso: invia messaggi solo ai clienti che possono ragionevolmente aspettarsi di riceverli da te.

Gli ID e le credenziali specifici necessari, ovvero ID linea, ID modello e chiave API, vengono recuperati nei passaggi 1 e 2 riportati di seguito, quindi non devi procurarteli in anticipo. Per informazioni generali sul funzionamento dell'API di Aircall, consulta Aircall per sviluppatori: riferimenti API.

Passaggio 1: prepara il modello WhatsApp

Passaggi

1. Apri o crea il modello che vuoi inviare quando chi chiama accetta, ad esempio un messaggio di saluto che informa che un responsabile commerciale lo contatterà a breve.
2. Controlla se il corpo del modello contiene variabili:
   • Nessuna variabile (testo completamente statico): ti serve solo l'ID del modello.
   • Variabili posizionali ({{1}}, {{2}}): le chiavi della richiesta saranno {{1}}, {{2}} e così via.
   • Variabili denominate ({{name}}, {{order_id}}): le chiavi della richiesta devono corrispondere esattamente a questi nomi, incluse le maiuscole e le minuscole.

Importante: Un modello utilizza variabili posizionali oppure denominate, mai entrambe. La chiave inviata nella richiesta deve corrispondere a quella dichiarata dal modello, altrimenti la variabile non verrà compilata.

Passaggio 2: recupera l'ID della linea, l'ID del modello e le credenziali API

Per la richiesta sono necessari tre elementi, tutti recuperati dall'API pubblica.

ID API e token API 

Vai al Dashboard Aircall, quindi a  Integrazioni > Chiavi API > Genera chiave API. Copia subito il token, perché non verrà mostrato di nuovo. Queste sono le credenziali utilizzate dal widget per l'autenticazione.

ID linea 

È l'ID del numero compatibile con WhatsApp da cui viene inviato il modello. Recuperalo con l'endpoint Elenca tutti i numeri; ogni numero nella risposta ha un id, che corrisponde al tuo lineId.

ID modello 

Recupera i modelli associati al numero compatibile con WhatsApp mediante l'endpoint Elenca modelli WhatsApp e copia l'id del modello del passaggio 1.

Passaggio 3: crea il flusso nell'editor di flussi

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 WhatsApp:

   • Come opzione di menu:

     Aggiungi un widget del menu IVR, ad esempio: "Per continuare su WhatsApp 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 WhatsApp e configura la richiesta come segue. Questa richiesta utilizza l'endpoint Invia un messaggio WhatsApp nella conversazione dell'agente.

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 genera automaticamente l'autorizzazione, senza richiedere alcuna codifica manuale.

Configurazione della richiesta

• Metodo: POST
• URL: https://api.aircall.io/v1/messages/send/whatsapp/native
• Corpo della richiesta, modello con variabili:

{
  "lineId": 1018591,
  "externalNumber": "{{callerNumber}}",
  "templateParams": {
    "id": "13779",
    "body": [
      { "key": "{{1}}", "value": "Jordan" },
      { "key": "{{2}}", "value": "2026-06-15" }
    ]
  }
}

• Corpo della richiesta, modello senza variabili:

{
  "lineId": 1018591,
  "externalNumber": "{{callerNumber}}",
  "templateParams": {
    "id": "12029"
  }
}

• Riferimento dei campi:
  • lineId: l'ID del numero abilitato a WhatsApp (il mittente), indicato nel passaggio 2.
  • externalNumber: il numero a cui viene inviato il modello. Usa {{callerNumber}} affinché l'editor di flussi inserisca il numero del chiamante durante l'esecuzione.
  • templateParams.id: l'ID del modello approvato, indicato nel passaggio 2.
  • templateParams.body: includilo solo quando il modello contiene variabili. Omettilo completamente per un modello statico.
  • key: deve corrispondere esattamente al segnaposto del modello ({{1}} per i modelli posizionali oppure il nome esatto per quelli con parametri denominati).
  • value: un valore statico o una variabile del flusso di chiamata.

Importante: {{callerNumber}} invia il modello al numero dal quale sta chiamando il chiamante. Se tale numero non è registrato su WhatsApp, la consegna non riuscirà. Tienilo presente quando decidi se offrire l'opzione WhatsApp a ogni chiamante.

Configurazione della risposta

L'interfaccia utente del widget richiede una risposta in base alla quale eseguire l'instradamento, anche se questo flusso non ne utilizza alcuna (la chiamata viene chiusa nel passaggio successivo indipendentemente dal risultato). Compila questi campi con valori segnaposto per consentire il salvataggio della configurazione:

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

Nota: L'API pubblica di Aircall è limitata a 120 richieste al minuto per azienda. Ciò non dovrebbe influire su un flusso di chiamata tipico, ma è opportuno saperlo se esegui test su larga scala.

Passaggio 5: chiudi il flusso di chiamata

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

Passaggi:

1. Dopo il widget, fai clic su + e aggiungi un Messaggio audio, ad esempio: "Ti abbiamo appena inviato un messaggio WhatsApp. Puoi rispondere lì quando vuoi. Arrivederci".

   

2. Termina la chiamata oppure, come soluzione alternativa, indirizzala alla segreteria telefonica o a un altro team.

Passaggio 6: testa il flusso

Passaggi

1. Fai clic sul pulsante Pubblica nell'angolo in alto a destra
2. Chiama il numero da un telefono il cui numero è registrato su WhatsApp.
3. Raggiungi il ramo WhatsApp (seleziona l'opzione o attiva la condizione di overflow).
4. Verifica di ricevere il modello, che tutte le variabili siano compilate correttamente e che, rispondendo, si apra 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

FAQ

Se il chiamante risponde, gli agenti vedranno la conversazione WhatsApp?

Sì. Questa richiesta utilizza l'endpoint Invia messaggio WhatsApp nella conversazione dell'agente, quindi sia il messaggio in uscita sia la risposta del cliente sono visibili agli agenti nella posta in arrivo di Aircall.

Posso utilizzare un modello con variabili sia posizionali sia denominate?

No. Un modello utilizza variabili posizionali oppure denominate, mai entrambe. Le chiavi nella richiesta devono corrispondere esattamente a quelle dichiarate dal modello.

Cosa accade se il numero del chiamante non è registrato su WhatsApp?

Il recapito non riesce. Poiché il messaggio viene inviato al numero da cui il chiamante ha effettuato la chiamata, è opportuno valutare questo aspetto prima di offrire l'opzione WhatsApp a tutti i chiamanti anziché a un segmento specifico.