Genuka WA docs

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.terminated e call.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

  1. Arriva il webhook call.connect con data.callId, data.from (il cliente) e data.session.sdp, l'offerta SDP del cliente.
  2. Il tuo stack costruisce la sua risposta SDP e la invia subito come pre_accept: l'audio può stabilirsi mentre l'agente risponde.
  3. Quando l'agente è pronto, accept con la stessa risposta SDP.
  4. terminate per riagganciare. call.terminated arriva in ogni caso, con la durata.
POST /api/v1/calls
{ "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.

  1. Verificalo: GET /api/v1/calls/permissions?waId=+237690000001&connectionId=con_1. Se canCall è true, vai al passaggio 3.

  2. 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: canRequestPermission false significa aspettare, non chiedere di nuovo.

  3. 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:

POST /api/v1/messages
{ "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

StatoerrorCosa fare
403plan_feature_unavailablePassa al piano Growth.
409calling_unavailable_coexistenceUsa un numero non condiviso con l'app WhatsApp Business.
400invalid_call_actionCorreggi il corpo: l'elenco completo è in issues.
422meta_errorLeggi il messaggio di Meta: numero non idoneo, nessun permesso, paese escluso…

Il riferimento completo è in API · Chiamate WhatsApp, e l'SDK TypeScript in Calling.

In questa pagina