Webhook delle chiamate WhatsApp: eventi della Calling API e chiamate su un numero Coexistence
Il campo calls riporta gli eventi della Calling API di WhatsApp Business: connect con un SDP answer o un SDP offer, stati della chiamata RINGING, ACCEPTED e REJECTED, terminate con COMPLETED o FAILED e la durata, e call_recording_available o call_transcription_available. La guida Coexistence di Meta indica le chiamate vocali e video come invariate nell'app WhatsApp Business e non supportate sulla Cloud API, quindi restano sul telefono.
easyCoexistence collega il numero dell'app WhatsApp Business alla Cloud API di Meta tramite Coexistence, così la tua AI e le automazioni rispondono ai messaggi e inviano template, mentre le chiamate continuano a squillare nell'app sul telefono.
Chiamate vocali e video sulla Cloud API per un numero collegato con l'app WhatsApp Business; nell'app restano invariate.
Limite minimo giornaliero di messaggi, in destinatari unici, che un numero deve avere prima di usare la Calling API.
Per quanto tempo le registrazioni e le trascrizioni restano scaricabili dopo la consegna del relativo webhook.
Il prefisso degli ID delle chiamate, il valore che collega i webhook connect, stati e terminate di una stessa chiamata.
Il permesso che un'app deve avere per ricevere i webhook delle chiamate, lo stesso richiesto per i messaggi.
Cosa riporta il campo calls?
Tutto ciò che accade a una chiamata effettuata o ricevuta tramite la Calling API, in un unico campo con un evento per ogni fase. Una chiamata avviata dall'azienda produce un evento connect, aggiornamenti di stato e un evento terminate. Le chiamate gestite via SIP riportano call_created al posto di connect, senza la sessione SDP. Un evento correlato si trova altrove: quando un cliente risponde a una richiesta di permesso di chiamata, la risposta arriva sul campo messages come messaggio interattivo di tipo call_permission_reply.
Come si presenta un webhook delle chiamate?
La stessa busta di ogni webhook WhatsApp, con un array calls sotto value e field impostato su calls. direction indica BUSINESS_INITIATED o USER_INITIATED; from e to riportano i numeri di telefono, to_user_id il BSUID del cliente, e uno dei due numeri può mancare per un cliente che usa un nome utente. metadata.phone_number_id identifica il tuo numero, come su qualsiasi altro campo. Questo è l'esempio Call Connect di Meta, con i segnaposto come li riporta Meta:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "16315553601",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"contacts": [
{
"profile": {
"name": "<CALLEE_NAME>",
"username": "<USERNAME>"
},
"wa_id": "16315553602",
"user_id": "<BSUID>",
"parent_user_id": "<PARENT_BSUID>"
}
],
"calls": [
{
"id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
"to": "16315553601",
"to_user_id": "<BSUID>",
"to_parent_user_id": "<PARENT_BSUID>",
"from": "16315553602",
"event": "connect",
"timestamp": "1671644824",
"direction": "BUSINESS_INITIATED",
"session": {
"sdp_type": "answer",
"sdp": "<<RFC 8866 SDP>>"
}
}
]
},
"field": "calls"
}
]
}
]
}Quali campi aggiunge l'evento terminate?
terminate è l'evento che la maggior parte dei sistemi salva, perché chiude la chiamata. I suoi campi, secondo il riferimento di Meta:
- status: COMPLETED quando la chiamata si è conclusa senza errori imprevisti, incluse le chiamate senza risposta; FAILED quando non si è connessa o si è interrotta.
start_time,end_timee duration in secondi: presenti solo se l'altra parte ha risposto.- errors: code, message, href ed
error_data.details su una chiamata FAILED. biz_opaque_callback_data: la tua stringa di tracciamento, quando ne hai passata una all'avvio o all'accettazione della chiamata.
I webhook delle chiamate funzionano su un numero Coexistence?
La guida Coexistence di Meta risponde nella sua tabella delle funzionalità: le chiamate vocali e video non cambiano nell'app WhatsApp Business e non sono supportate sulla Cloud API per un numero collegato in questo modo. I prerequisiti della Calling API stessa dicono lo stesso dall'altro lato: il numero aziendale deve essere in uso con la Cloud API, non con l'app WhatsApp Business. Quindi su un numero Coexistence i clienti continuano a chiamare come prima, la chiamata squilla nell'app sul telefono e il campo calls non ha nulla da riportare. Un'azienda che ha bisogno delle chiamate nel software usa un numero solo sulla Cloud API.
Come si collegano gli eventi di una stessa chiamata?
Tramite l'ID della chiamata, che inizia con wacid e si ripete in ogni evento di quella chiamata. Una chiamata avviata dall'azienda riporta connect con la SDP answer, gli stati RINGING e poi ACCEPTED o REJECTED, e infine terminate. Una chiamata avviata dall'utente riporta connect con una SDP offer da far gestire al tuo stack, poi terminate. Gli eventi di registrazione e trascrizione, quando attivi, arrivano dopo terminate. Usa come chiave id più event, perché i nuovi tentativi ripetono gli invii e l'ordine di arrivo non è garantito. L'elenco completo dei prerequisiti della Calling API è nella pagina sulle chiamate su un numero Coexistence.
Cosa può fare la tua AI con le chiamate su un numero Coexistence?
Lavorare nella chat, mentre le chiamate restano alla persona al telefono. easyCoexistence non si iscrive al campo calls e non ha strumenti per le chiamate; il suo connettore e le automazioni coprono messaggi e template. In pratica una risposta dell'AI può dire a un cliente quando qualcuno è disponibile a parlare e quale numero chiamare, un'automazione a parole chiave può rispondere a "chiamata" o "telefono" con queste informazioni, e il titolare risponde alla chiamata nell'app WhatsApp Business come prima.
Errori comuni
- Iscriversi a calls per un numero Coexistence e aspettare gli eventi. Meta indica le chiamate come non supportate sulla Cloud API per questi numeri.
- Aspettarsi start_time e duration in ogni terminate. Compaiono solo quando la chiamata è stata risposta; una chiamata senza risposta termina comunque con COMPLETED.
- Cercare le risposte ai permessi nel campo calls. Arrivano su messages, come call_permission_reply interattivo.
- Lasciare le registrazioni e le trascrizioni presso Meta. Entrambe possono essere scaricate per 7 giorni dopo il loro webhook, poi scompaiono.
Ogni numero è monitorato 24/7, inclusa la regola dei 14 giorni che disconnette un numero la cui app non viene aperta. Da US$ 9 fino a US$ 0,75 per numero al mese, in calo man mano che aggiungi numeri, con i primi 3 giorni gratis.
Domande frequenti
I clienti perdono il pulsante di chiamata quando un numero si collega all'API tramite Coexistence?
La guida Coexistence di Meta indica le chiamate vocali e video come invariate nell'app WhatsApp Business. I clienti chiamano lo stesso numero, e il titolare risponde nell'app sul telefono.
La Calling API ha lo stesso prezzo dei messaggi?
No. La pagina dei prezzi di Meta dice che la Calling API ha una tariffazione diversa e rimanda a un documento separato sui prezzi delle chiamate, quindi i costi delle chiamate non compaiono nell'oggetto pricing degli stati dei messaggi.
Una chiamata della Calling API può essere registrata o trascritta?
Sì, quando la registrazione o la trascrizione è attiva. Dopo la chiamata, Meta invia call_recording_available con un ID media audio oppure call_transcription_available con un ID documento JSON, di solito entro un minuto.
Un webhook delle chiamate può andare a un endpoint diverso da quello dell'app?
Sì. calls è uno dei campi che Meta permette a un account WhatsApp Business o a un numero di telefono di instradare verso un URL di callback alternativo, insieme a messages e ai campi Coexistence.
Continua a leggere
Pronto per iniziare?
Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.
Inizia la prova gratuitaVerificato il