Genuka WA docs

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

  1. Le webhook call.connect arrive avec data.callId, data.from (le client) et data.session.sdp, l'offre SDP du client.
  2. 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.
  3. Quand l'agent est prêt, accept avec la même réponse SDP.
  4. terminate pour raccrocher. call.terminated arrive dans tous les cas, avec la durée.
POST /api/v1/calls
{ "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.

  1. Vérifiez-la : GET /api/v1/calls/permissions?waId=+237690000001&connectionId=con_1. Si canCall est vrai, passez à l'étape 3.

  2. Sinon, et si canRequestPermission est 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.

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

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

StatuterrorCe qu'il faut faire
403plan_feature_unavailablePasser à la formule Growth.
409calling_unavailable_coexistenceUtiliser un numéro qui n'est pas partagé avec l'app WhatsApp Business.
400invalid_call_actionCorriger le corps : la liste complète est dans issues.
422meta_errorLire 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.

Sur cette page