Collegare un agente vocale alle chiamate WhatsApp
Ricevi ed effettua chiamate WhatsApp con il tuo agente vocale o il tuo stack WebRTC: attivare le chiamate, webhook call.*, azioni di chiamata con SDP, permessi.
Genuka WA inoltra le chiamate WhatsApp al tuo stack: un agente vocale, un softphone WebRTC, un contact center. Attivi le chiamate per il numero, ricevi ogni chiamata via webhook con il suo SDP e rispondi tramite l'API. L'audio passa direttamente tra Meta e il tuo stack; non transita mai da Genuka WA. Le chiamate sono incluse a partire dal piano Growth.
Prima di iniziare
- Il numero deve essere idoneo. Meta riserva le chiamate ai numeri con un volume di
conversazioni sufficiente, ed esclude alcuni paesi (tra cui Stati Uniti, Canada e Nigeria).
Quando non si applica, Meta rifiuta con il proprio messaggio, inoltrato così com'è (
422). - Non in coesistenza. Un numero condiviso con l'app WhatsApp Business non ha chiamate via API
(
409 calling_unavailable_coexistence). - Un webhook iscritto alle chiamate. Iscrivi un endpoint a
call.connect,call.status_changed,call.terminatedecall.permission_replied(vedi Webhook).
1. Attiva le chiamate per il numero
curl -X PATCH https://wa.genuka.com/api/v1/numbers/con_1/calling \
-H "Authorization: Bearer pk_live_…" -H "Content-Type: application/json" \
-d '{ "status": "ENABLED" }'La pagina del numero nella dashboard ha lo stesso interruttore. callHours limita le chiamate in
arrivo ai tuoi orari di apertura; callbackPermissionStatus fa sì che un cliente che ti chiama ti
autorizzi a richiamarlo.
2. Un cliente ti chiama
- Arriva il webhook
call.connectcondata.callId,data.from(il cliente) edata.session.sdp, l'offerta SDP del cliente. - Il tuo stack costruisce la sua risposta SDP e la invia subito come
pre_accept: l'audio può stabilirsi mentre l'agente risponde. - Quando l'agente è pronto,
acceptcon la stessa risposta SDP. terminateper riagganciare.call.terminatedarriva in ogni caso, con la durata.
{ "action": "pre_accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\n… (la tua risposta SDP)" }La chiamata squilla per circa 30 secondi. L'intero percorso, dal webhook al tuo pre_accept,
deve starci dentro: conferma subito la ricezione del webhook e gestisci la chiamata in parallelo.
Basta callId, senza connectionId: Genuka WA sa a quale numero appartiene la chiamata (altrimenti
404 call_not_found: passa il connectionId).
Le iscrizioni si basano sul campo di Meta
I webhook sono filtrati per campo di Meta: iscriversi a call.permission_replied porta anche gli
eventi message.*, perché la risposta è un messaggio. Filtra sul type della busta. Il
bizOpaqueCallbackData di un'azione di chiamata torna come data.callbackData.
3. Chiami un cliente
Meta richiede il permesso del cliente prima di qualsiasi chiamata in uscita.
-
Verificalo:
GET /api/v1/calls/permissions?waId=+237690000001&connectionId=con_1. SecanCallè true, vai al passaggio 3. -
Altrimenti, e se
canRequestPermissionè true, chiedilo (dentro la finestra di 24 ore):POST /api/v1/messages { "connectionId": "con_1", "to": "+237690000001", "callPermissionRequest": { "body": "We would like to call you back about your order." } }La risposta del cliente arriva come
call.permission_replied. Meta limita quante volte puoi chiedere per cliente e al giorno:canRequestPermissionfalse significa aspettare, non chiedere di nuovo. -
Avvia la chiamata con la tua offerta SDP. La risposta SDP del cliente arriva su
call.connect.POST /api/v1/calls { "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (la tua offerta SDP)" }
Lascia che il cliente ti chiami
Un pulsante di chiamata WhatsApp, in una conversazione aperta, permette al cliente di chiamarti con un tocco:
{ "connectionId": "con_1", "to": "+237690000001",
"voiceCall": { "body": "Any question? Call us on WhatsApp.", "displayText": "Call" } }Fuori dalla finestra di 24 ore, usa un modello con un pulsante VOICE_CALL.
Errori da conoscere
| Stato | error | Cosa fare |
|---|---|---|
403 | plan_feature_unavailable | Passa al piano Growth. |
409 | calling_unavailable_coexistence | Usa un numero non condiviso con l'app WhatsApp Business. |
400 | invalid_call_action | Correggi il corpo: l'elenco completo è in issues. |
422 | meta_error | Leggi il messaggio di Meta: numero non idoneo, nessun permesso, paese escluso… |
Il riferimento completo è in API · Chiamate WhatsApp, e l'SDK TypeScript in Calling.
API WhatsApp per agenti IA: server MCP, llms.txt
Collega Claude, Cursor o VS Code all'API WhatsApp Business con il server MCP di Genuka WA, più llms.txt, documentazione in Markdown e una specifica OpenAPI.
Riferimento dell'API
Una sola API per gestire tutto in modo programmatico: numeri, modelli, messaggi, campagne e il tuo abbonamento.