Connect a voice agent to WhatsApp calls
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.terminatedandcall.permission_replied(see Webhooks).
1. Turn calls on for the number
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
- The
call.connectwebhook arrives withdata.callId,data.from(the customer) anddata.session.sdp, the customer's SDP offer. - Your stack builds its SDP answer and sends it right away as
pre_accept: the audio can set up while the agent picks up. - When the agent is ready,
acceptwith the same SDP answer. terminateto hang up.call.terminatedarrives either way, with the duration.
{ "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).
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.
-
Check it:
GET /api/v1/calls/permissions?waId=+237690000001&connectionId=con_1. IfcanCallis true, go to step 3. -
Otherwise, and if
canRequestPermissionis true, ask for it (inside the 24-hour window):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:canRequestPermissionfalse means wait, not ask again. -
Start the call with your SDP offer. The customer's SDP answer arrives on
call.connect.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:
{ "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, and the TypeScript SDK in Calling.
WhatsApp API for AI agents: MCP server, llms.txt
Connect Claude, Cursor or VS Code to the WhatsApp Business API with the Genuka WA MCP server, plus llms.txt, Markdown docs and an OpenAPI spec.
API reference
One API to drive everything programmatically: numbers, templates, messages, campaigns and your subscription.