# Connect a voice agent to WhatsApp calls

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

> Receive and place WhatsApp calls with your own voice agent or WebRTC stack: turn calls on, call.* webhooks, call actions with SDP, permissions.

Genuka WA relays WhatsApp calls to your own stack: a voice agent, a WebRTC softphone, a contact
center. You turn calls on for the number, receive each call by webhook with its SDP, and answer
through the API. The audio flows directly between Meta and your stack; it never goes through
Genuka WA. Calls are included from the Growth plan.

## Before you start

* **The number must be eligible.** Meta keeps calls for numbers with enough conversation volume,
  and excludes a few countries (the United States, Canada and Nigeria among them). When it does
  not apply, Meta refuses with its own message, passed through as is (`422`).
* **Not in coexistence.** A number shared with the WhatsApp Business app has no API calls
  (`409 calling_unavailable_coexistence`).
* **A webhook subscribed to calls.** Subscribe an endpoint to `call.connect`,
  `call.status_changed`, `call.terminated` and `call.permission_replied` (see
  [Webhooks](https://wa.genuka.com/en/docs/webhooks)).

## 1. Turn calls on for the number

```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" }'
```

The number's page in the dashboard has the same switch. `callHours` limits incoming calls to your
opening hours; `callbackPermissionStatus` makes a customer who calls you allow you to call back.

## 2. A customer calls you

1. The `call.connect` webhook arrives with `data.callId`, `data.from` (the customer) and
   `data.session.sdp`, the customer's SDP offer.
2. Your stack builds its SDP answer and sends it right away as `pre_accept`: the audio can set up
   while the agent picks up.
3. When the agent is ready, `accept` with the same SDP answer.
4. `terminate` to hang up. `call.terminated` arrives either way, with the duration.

```json title="POST /api/v1/calls"
{ "action": "pre_accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\n… (your SDP answer)" }
```

The call rings for about **30 seconds**. The whole trip, from the webhook to your `pre_accept`,
has to fit in it: acknowledge the webhook at once and handle the call alongside. `callId` alone is
enough, no `connectionId`: Genuka WA knows which number the call belongs to (otherwise `404
call_not_found`: pass the `connectionId`).

> [!NOTE]
> **Subscriptions match on Meta's field**
>
> Webhooks are filtered by Meta field: subscribing to `call.permission_replied` also brings the
> `message.*` events, since the answer is a message. Filter on the envelope's `type`. The
> `bizOpaqueCallbackData` of a call action comes back as `data.callbackData`.

## 3. You call a customer

Meta requires the customer's permission before any outgoing call.

1. Check it: `GET /api/v1/calls/permissions?waId=+237690000001&connectionId=con_1`. If `canCall`
   is true, go to step 3.
2. Otherwise, and if `canRequestPermission` is true, ask for it (inside the 24-hour window):

   ```json title="POST /api/v1/messages"
   { "connectionId": "con_1", "to": "+237690000001",
     "callPermissionRequest": { "body": "We would like to call you back about your order." } }
   ```

   The customer's answer arrives as `call.permission_replied`. Meta caps how often you may ask
   per customer and per day: `canRequestPermission` false means wait, not ask again.
3. Start the call with your SDP offer. The customer's SDP answer arrives on `call.connect`.

   ```json title="POST /api/v1/calls"
   { "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (your SDP offer)" }
   ```

## Let the customer call you

A WhatsApp call button, in an open conversation, lets the customer call you in one tap:

```json title="POST /api/v1/messages"
{ "connectionId": "con_1", "to": "+237690000001",
  "voiceCall": { "body": "Any question? Call us on WhatsApp.", "displayText": "Call" } }
```

Outside the 24-hour window, use a template with a `VOICE_CALL` button.

## Errors worth knowing

| Status | `error`                           | What to do                                                                 |
| ------ | --------------------------------- | -------------------------------------------------------------------------- |
| `403`  | `plan_feature_unavailable`        | Move to the Growth plan.                                                   |
| `409`  | `calling_unavailable_coexistence` | Use a number that is not shared with the WhatsApp Business app.            |
| `400`  | `invalid_call_action`             | Fix the body: the full list is in `issues`.                                |
| `422`  | `meta_error`                      | Read Meta's message: number not eligible, no permission, excluded country… |

The full reference is in [API · WhatsApp calls](https://wa.genuka.com/en/docs/api#whatsapp-calls), and the TypeScript
SDK in [Calling](https://wa.genuka.com/sdk/calling).
