Offrire Supporto WhatsApp ai chiamanti utilizzando il widget Inoltra 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 una coda o di respingerli quando tutti gli agenti sono occupati, puoi utilizzare il tuo IVR per offrire loro supporto tramite WhatsApp. Quando una persona 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 dei tuoi agenti, dove viene gestita come qualsiasi altra conversazione WhatsApp.

Questa soluzione è utile in due situazioni comuni:

• Scelta proattiva: offri subito WhatsApp, così chi preferisce inviare 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 Smartflows, inclusi un corpo JSON e l'autenticazione di base. Non devi essere uno sviluppatore, ma dovresti essere in grado di seguire istruzioni tecniche dettagliate.

Come funziona

1. Un cliente chiama il tuo numero Aircall e accede al tuo IVR di Smartflows.
2. La persona raggiunge un punto in cui viene offerto WhatsApp, come opzione di 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 Chiama tramite API invia una richiesta all'endpoint di Messaggistica WhatsApp di Aircall, specificando la linea da cui inviare il messaggio, il modello da utilizzare e il numero a cui inviarlo (il numero della persona che chiama).
4. La persona riceve il messaggio WhatsApp e può rispondere. La sua risposta apre una conversazione nella Posta in arrivo di Aircall, visibile ai tuoi agenti.
5. La chiamata termina con una breve conferma vocale.

Importante: Il widget Chiama tramite API invia la richiesta, ma non può diramare la chiamata in base alla risposta dell'API. Tutto ciò che segue il widget (un messaggio di conferma, la fine della chiamata o un percorso alternativo) deve avvenire indipendentemente dal fatto che il messaggio sia stato effettivamente inviato.

Prima di iniziare

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

• Disponi di un Piano Aircall Professionale o Personalizzato. Il widget Chiama tramite API non è disponibile con altri Piani.
• Disponi dell'accesso come Amministratore al Dashboard Aircall e a Smartflows.
• Disponi di un numero compatibile con WhatsApp nel tuo Il mio conto, con la Messaggistica WhatsApp abilitata.
• Disponi di un modello WhatsApp già approvato da WhatsApp/Meta oppure puoi crearne uno.

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

Gli ID e le credenziali specifici necessari (ID linea, ID modello, chiave API) vengono recuperati nei passaggi 1 e 2 seguenti, quindi non devi raccoglierli 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 desideri inviare quando una persona accetta questa opzione (ad esempio, un saluto che le comunica che un responsabile commerciale la 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 maiuscole e 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 servono tre elementi, tutti recuperati dall'API pubblica.

ID API e token API 

Vai al Dashboard Aircall, quindi a Impostazioni azienda > Chiavi API > Aggiungi una nuova 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 contiene un id, che corrisponde al tuo lineId.

ID modello 

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

Passaggio 3: crea il flusso in Smartflows

1. Vai a Dashboard Aircall > Numeri > Numeri
2. Seleziona il numero e fai clic sul pulsante verde Modifica per aprire Smartflows
3. Decidi dove offrire WhatsApp:

   • Come opzione di menu:

     Aggiungi un widget di 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 Instrada tramite API

Aggiungi il widget Instrada tramite API al 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 crea automaticamente l'autorizzazione, senza necessità di 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 tuo Numero abilitato a WhatsApp (il mittente), ottenuto nel passaggio 2.
  • externalNumber: il Numero al quale viene inviato il modello. Utilizza {{callerNumber}} affinché Smartflows inserisca il Numero del chiamante durante l'esecuzione.
  • templateParams.id: l'ID del modello approvato, ottenuto 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 o il nome esatto per quelli con nomi).
  • value: un valore statico o una variabile Smartflows.

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 solo 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. Questo non dovrebbe influire su un tipico Flusso delle chiamate, ma è utile saperlo se stai eseguendo test con volumi elevati.

Passaggio 5: chiudi il Flusso delle chiamate

Poiché il widget non può reagire alla risposta dell'API, completa 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 messaggio WhatsApp. Puoi rispondere lì quando vuoi. Arrivederci."

   

2. Termina la chiamata oppure instradala alla Segreteria telefonica o a un altro Team come soluzione alternativa.

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

I miei Agenti vedranno la conversazione WhatsApp se il chiamante risponde?

Sì. Questa richiesta utilizza l'endpoint Invia un messaggio WhatsApp nella conversazione dell'Agente, quindi sia il messaggio in uscita sia la risposta del cliente sono visibili agli Agenti nella loro Posta in arrivo di Aircall.

Posso usare un modello con variabili sia posizionali che denominate?

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

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

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