# Brancher un agent vocal sur les appels WhatsApp

URL: https://wa.genuka.com/docs/guides/voice-agent
Language: French

> 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](https://wa.genuka.com/docs/webhooks)).

## 1. Activer les appels sur le numéro

```bash
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.

```json title="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`).

> [!NOTE]
> **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) :

   ```json title="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`.

   ```json title="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 :

```json title="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

| 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](https://wa.genuka.com/docs/api#appels-whatsapp), et le SDK
TypeScript dans [Calling](https://wa.genuka.com/sdk/calling).
