Voice Calls

Note

POST https://api.whatbot.in/public/v1/calls — place a WhatsApp voice call to a contact. Calls to a customer require their explicit permission first; inbound calls from customers are always free and need no permission.

How WhatsApp calling differs from a normal dialler

You cannot simply dial a customer. WhatsApp requires the customer to accept a call permission request before your business can call them, and Meta enforces how often you may ask:

Rule	Limit
Permission requests per contact	1 per 24 hours, 2 per week
Calling window once accepted	7 days
Consecutive unanswered calls before permission is revoked	4

Inbound (customer-initiated) calls bypass all of this — they are free and need no permission (except from the countries listed under Geo restrictions).

Request permission to call

cURL

curl -X POST https://api.whatbot.in/public/v1/calls/permission-request \
  -H "X-API-Key: wa_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "wa_id": "918610173741" }'

The contact receives a prompt in WhatsApp asking whether your business may call them. Their answer arrives asynchronously — subscribe to call.permission.updated (see Webhooks) or poll the endpoint below.

Check request_sent before telling anyone they were asked

A 200 does not always mean the contact received a prompt. When WhatsApp already permits calling — usually because the contact rang you — this reconciles your permission and returns without messaging them, since asking would be redundant and would spend one of your 1-per-24h requests for nothing.

request_sent	What happened
true	The contact received the prompt. Wait for their answer.
false	Nothing was sent. You may already call them — check status.

Response

{
  "wa_id": "918610173741",
  "status": "requested",
  "requested_at": "2026-08-18T12:04:11+00:00",
  "request_sent": true,
  "can_call": false,
  "can_call_reason": "permission not granted (status=requested)",
  "can_request": false,
  "can_request_reason": "limit reached: 1 request per 24h"
}

This is the same shape GET /permission returns, plus request_sent. The can_* fields are computed from the row and the clock rather than stored, so they answer “may I act right now” without you having to re-derive the cadence and window rules.

Cadence is enforced

Asking again too soon returns 429 with the reason, e.g. limit reached: 1 request per 24h. So does asking for a contact who has already approved you and whose window is still open — there is nothing to ask for, and re-asking used to quietly extend the calling window by another seven days with no action from the contact at all.

The permission request is itself a WhatsApp message, so it is also subject to the 24-hour messaging window. Outside the window this returns 422 before anything is spent — ask the contact to message you first. A template you send does not reopen the window; only the contact’s reply does.

409 when calling was revoked on our side

After four consecutive unanswered calls we revoke calling for that contact. That is our rule, not WhatsApp’s, so WhatsApp may well still permit the call. When it does, this endpoint returns 409 rather than reconciling it away (when WhatsApp no longer permits it, a new request is sent as usual):

Calling was revoked for this contact after 4 unanswered calls. Meta still
permits it, but our own rule does not — it clears when the contact calls you.

It clears by itself the moment the contact rings you. An ordinary reply does not clear it: the only writer that lifts our own revocation runs on an inbound call. Retrying the request does nothing, which is why this is an error and not a 200.

Check permission state

cURL

curl https://api.whatbot.in/public/v1/calls/permission/918610173741 \
  -H "X-API-Key: wa_live_xxx"

{
  "wa_id": "918610173741",
  "status": "approved",
  "expires_at": "2026-08-25T12:09:02+00:00",
  "can_call": true,
  "can_call_reason": "",
  "can_request": false,
  "can_request_reason": "already approved — calling window is still open"
}

status is one of none, requested, approved, rejected, expired, revoked. Always branch on can_call rather than re-deriving the rules yourself.

Place a call

cURL

curl -X POST https://api.whatbot.in/public/v1/calls \
  -H "X-API-Key: wa_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "wa_id": "918610173741",
    "sdp": "v=0\r\no=- 0 0 IN IP4 127.0.0.1\r\n..."
  }'

sdp is a WebRTC offer generated by your own media stack. WhatsApp calling uses WebRTC (ICE + DTLS + SRTP, OPUS by default); Whatbot relays the signalling but never terminates the audio, so the offer must come from the endpoint that will carry the call.

Returns 403 with the reason when permission is missing or expired, and 422 when the destination is geo-restricted. The call goes out from the business number of the contact’s most recent conversation, or the workspace’s default number if there is none.

200

{
  "id": "0f6b...",
  "wa_call_id": "wacid...",
  "wa_id": "918610173741",
  "direction": "outbound",
  "status": "ringing",
  "started_at": "2026-08-18T12:10:00+00:00",
  "dest_country": null,
  "conversation_id": "c9e6f0f7-..."
}

What happens next — answered, missed, ended — arrives on the call.* webhooks and in the call log.

Call log

cURL

curl "https://api.whatbot.in/public/v1/calls?direction=outbound&limit=20" \
  -H "X-API-Key: wa_live_xxx"

{
  "calls": [
    {
      "id": "0f6b...",
      "wa_id": "918610173741",
      "direction": "outbound",
      "status": "completed",
      "started_at": "2026-08-18T12:10:00+00:00",
      "answered_at": "2026-08-18T12:10:06+00:00",
      "ended_at": "2026-08-18T12:11:02+00:00",
      "duration_sec": 56,
      "billable_sec": 60
    }
  ]
}

Field	Type	Required	Description
direction	string		inbound or outbound.
status	string		ringing, connected, completed, missed, rejected or failed.
conversation_id	string		Only calls on this conversation.
limit	number		1–200. Defaults to 50.
offset	number		Skip this many, for paging. Defaults to 0.

Newest first. Each call carries its conversation_id when one exists, and the contact’s contact_name when known. wa_id is masked if your workspace masks the public API.

GET /calls/{call_id} returns one call by its id, or 404.

Billing

WhatsApp bills answered outbound calls only, rounded up to 6-second increments. Ringing and unanswered calls are free, and inbound calls are always free. billable_sec is the rounded figure — a 56-second call bills as 60 — and is 0 for anything free.

Geo restrictions

Direction	Restriction
Inbound	Unavailable for numbers in Cuba, Iran, North Korea, Syria
Outbound	Blocked when your business number originates in US, Canada, Egypt, Vietnam, Nigeria

Note the outbound rule keys off your number’s country, not the customer’s. Blocked attempts return 422 before any call is placed.

Webhook events

Subscribe via Webhooks — these are opt-in and not included in the default event set:

Event	Fires when
call.permission.requested	You sent a permission request
call.permission.updated	The contact accepted or declined, or a stale permission was reconciled
call.started	A customer’s call to you started ringing (inbound only)
call.completed	An answered call ended
call.missed	A call ended unanswered, declined or failed

Payloads are listed on the Webhooks page.

Errors

Status	Cause
403	POST /calls without an approved, unexpired permission
404	GET /calls/{call_id} for a call that isn’t in your workspace
409	Calling was revoked after four unanswered calls and WhatsApp still permits it (permission request)
422	Invalid wa_id; geo-restricted number; the 24-hour window is closed (permission request)
429	Permission-request limit reached, or the contact has already approved you
502	WhatsApp rejected the request or the call