Genuka WA docs

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

  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.
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).

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):

    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.

    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:

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

StatuserrorWhat to do
403plan_feature_unavailableMove to the Growth plan.
409calling_unavailable_coexistenceUse a number that is not shared with the WhatsApp Business app.
400invalid_call_actionFix the body: the full list is in issues.
422meta_errorRead Meta's message: number not eligible, no permission, excluded country…

The full reference is in API · WhatsApp calls, and the TypeScript SDK in Calling.

On this page