Brancher un agent vocal sur les appels WhatsApp
Recevoir et passer des appels WhatsApp avec votre propre agent vocal ou WebRTC : activer les appels, webhooks call.*, actions d'appel avec SDP, autorisations.
Genuka WA relaie les appels WhatsApp vers votre propre système : un agent vocal, un softphone WebRTC, un centre d'appels. Vous activez les appels sur le numéro, vous recevez chaque appel par webhook avec son SDP, et vous répondez par l'API. Le son circule directement entre Meta et votre système ; il ne passe jamais par Genuka WA. Les appels sont inclus à partir de la formule Growth.
Mis à jour le 17 novembre 2026
Avant de commencer
- Le numéro doit être éligible. Meta réserve les appels aux numéros qui ont un volume de
conversations suffisant, et exclut quelques pays (dont les États-Unis, le Canada et le Nigeria).
Quand ce n'est pas le cas, Meta refuse avec son propre message, renvoyé tel quel (
422). - Pas en coexistence. Un numéro partagé avec l'application WhatsApp Business n'a pas les appels
par l'API (
409 calling_unavailable_coexistence). - Un webhook abonné aux appels. Abonnez un endpoint à
call.connect,call.status_changed,call.terminatedetcall.permission_replied(voir Webhooks).
1. Activer les appels sur le numéro
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" }'Vous pouvez aussi le faire depuis la fiche du numéro, dans le tableau de bord. Les horaires
(callHours) limitent les appels entrants à vos heures d'ouverture ; callbackPermissionStatus
fait qu'un client qui vous appelle vous autorise à le rappeler.
2. Un client vous appelle
- Le webhook
call.connectarrive avecdata.callId,data.from(le client) etdata.session.sdp, l'offre SDP du client. - Votre système construit sa réponse SDP et l'envoie aussitôt en
pre_accept: le son peut s'établir pendant que l'agent décroche. - Quand l'agent est prêt,
acceptavec la même réponse SDP. terminatepour raccrocher.call.terminatedarrive dans tous les cas, avec la durée.
{ "action": "pre_accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\n… (votre réponse SDP)" }L'appel sonne environ 30 secondes. Tout le trajet, du webhook à votre pre_accept, doit tenir
dans ce délai : répondez au webhook immédiatement et traitez l'appel en parallèle. Le callId
suffit, sans connectionId : Genuka WA sait à quel numéro l'appel appartient (sinon, 404 call_not_found : passez le connectionId).
Abonnement par champ Meta
Les webhooks sont filtrés par champ Meta : s'abonner à call.permission_replied fait aussi
recevoir les message.*, car la réponse est un message. Filtrez sur le type de l'enveloppe.
Le bizOpaqueCallbackData d'une action d'appel revient dans data.callbackData.
3. Vous appelez un client
Meta exige l'autorisation du client avant tout appel sortant.
-
Vérifiez-la :
GET /api/v1/calls/permissions?waId=+237690000001&connectionId=con_1. SicanCallest vrai, passez à l'étape 3. -
Sinon, et si
canRequestPermissionest vrai, demandez-la (dans la fenêtre de 24 h) :POST /api/v1/messages { "connectionId": "con_1", "to": "+237690000001", "callPermissionRequest": { "body": "Nous aimerions vous rappeler au sujet de votre commande." } }La réponse du client arrive en
call.permission_replied. Meta limite le nombre de demandes par client et par jour :canRequestPermissionà faux veut dire attendre, pas redemander. -
Lancez l'appel avec votre offre SDP. La réponse SDP du client arrive sur
call.connect.POST /api/v1/calls { "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (votre offre SDP)" }
Faire appeler le client
Un bouton d'appel WhatsApp, dans une conversation ouverte, laisse le client vous appeler en un geste :
{ "connectionId": "con_1", "to": "+237690000001",
"voiceCall": { "body": "Une question ? Appelez-nous sur WhatsApp.", "displayText": "Appeler" } }Hors de la fenêtre de 24 h, utilisez un template avec un bouton VOICE_CALL.
Les erreurs à connaître
| Statut | error | Ce qu'il faut faire |
|---|---|---|
403 | plan_feature_unavailable | Passer à la formule Growth. |
409 | calling_unavailable_coexistence | Utiliser un numéro qui n'est pas partagé avec l'app WhatsApp Business. |
400 | invalid_call_action | Corriger le corps : la liste complète est dans issues. |
422 | meta_error | Lire le message de Meta : numéro non éligible, pas d'autorisation, pays exclu… |
La référence complète est dans API · Appels WhatsApp, et le SDK TypeScript dans Calling.