Everything needed to place an outbound WhatsApp voice call from your own backend: the permission prerequisite, the POST /calls request with an SDP offer, the Call Connect, status, and terminate webhooks, and the errors that stop a call before it rings. Dualhook's Meta app does not subscribe to calls, so these webhooks reach you only through your own Meta app's subscription, not through a Dualhook connection or its Webhook Override. Dualhook does not proxy call signalling or media.
Overview
Business-initiated calls (BIC) let your business place outbound voice calls to WhatsApp users. Normally the user must have granted you call permission first (see Call Permissions); permissions can be temporary (7 calendar days) or permanent. Numbers on quality-based calling can call without prior approval.
BIC is not available when the business phone number's country is United States, Canada, Egypt, Vietnam, or Nigeria. The recipient can be in any country where Cloud API is available.
Quality-Based Business-Initiated Calling
Limited availability. Eligible business phone numbers with a Colombia (+57) or Mexico (+52) country code are enrolled automatically when the Calling API is enabled, and eligible numbers that already had calling enabled have been migrated.
On these numbers you can call a WhatsApp user without prior approval, unless the user has declined permanent call permission or revoked a permission they granted earlier. Existing permissions stay valid after migration. The quality-based model uses only permanent permission; temporary and callback permissions do not apply.
Call attempts are limited per business phone number over a rolling 24 hours, by tier:
| Tier | Call attempts per rolling 24 hours |
|---|---|
CALLING_TIER_NO_ACCESS | Quality-based calling unavailable |
CALLING_TIER_1K | 1,000 |
CALLING_TIER_15K | 15,000 |
CALLING_TIER_UNLIMITED | No tier limit (other Calling API limits still apply) |
Only attempts to users without approved call permission count; calls to users who approved permission do not. Numbers start at CALLING_TIER_1K, and Meta moves them up automatically based on sustained calling usage, call quality, account standing, and active restrictions. There is no upgrade request.
- A tier change arrives as a
CALLING_TIER_UPDATEevent on theaccount_updatewebhook. - Going over the limit returns
138037. Wait until earlier attempts leave the rolling 24-hour window. - Poor call quality can get business-initiated calling restricted temporarily.
- Opt a number in or out with the
call_permission_modesetting. Opting in when the number isn't eligible returns138039.
Dualhook Boundary
Dualhook documents business-initiated calls but does not offer calling. There is no calling screen in the dashboard, Dualhook does not proxy call signaling or media, and the Runtime API has no /calls or /call_permissions route. Place and terminate calls with your own Meta app that has access to the number.
The Calling API is not available on Coexistence numbers, which most Dualhook connections are; outbound calls on those numbers are made from the WhatsApp Business app. Dualhook does not ingest calls webhooks.
Prerequisites
- Subscribe your app to the
callswebhook field. - Calling enabled on the business phone number (see Calling Configuration).
- Approved call permission from the recipient (error
138006if absent), unless the number uses quality-based calling. - Valid payment method on the WABA. UIC is free, but BIC is per-pulse billed (see Pricing).
- Business phone number country in the BIC-supported list.
The Four-Step BIC Flow
- Obtain permission. Send a call permission request (free-form or template) and wait for the user to accept, rely on
callback_permission_status: ENABLEDto auto-grant when the user calls you, or let the user grant permanent permission from your business profile. See Call Permissions. On a quality-based number, skip this step unless the user declined or revoked permission. - POST
/callswithaction: connectand an SDP offer from your WebRTC stack. - Apply the SDP answer Meta returns via the Call Connect webhook to your WebRTC stack to establish the media session. You'll then receive
RINGING,ACCEPTED, orREJECTEDstatus webhooks. - Terminate when done — either you POST
action: terminate, or the user hangs up. Either way, a Call Terminate webhook arrives.
The ACCEPTED status webhook typically arrives after the call is already established — Cloud API sends it primarily for auditing, not as a precondition for sending media.
Initiate a Call (POST /calls)
POST /<PHONE_NUMBER_ID>/calls
{
"messaging_product": "whatsapp",
"to": "12015550123",
"action": "connect",
"session": {
"sdp_type": "offer",
"sdp": "<<RFC 8866 SDP>>"
},
"biz_opaque_callback_data": "0fS5cePMok"
}
| Field | Notes |
|---|---|
to | Recipient WhatsApp user phone number. Required unless you send recipient. |
recipient | Optional. The user's BSUID or parent BSUID, instead of or in addition to to. If you send both, to takes precedence. |
action | connect for new calls. Other values: pre_accept, accept, reject, terminate (used for user-initiated calls) |
session.sdp_type | offer for BIC |
session.sdp | RFC 8866 SDP — OPUS only, 48 kHz media clock, 8 kHz DTMF clock, ptime 20ms, single SSRC. See API Reference → Media Path Guidelines |
biz_opaque_callback_data | Optional. Up to 512 chars. Echoed back in subsequent webhooks for tracking |
recording / transcription | Optional. Opt this call into recording or transcription. See Call Recording & Transcription |
messaging_account_id | Optional. The Messaging account the call is placed from. Include it whenever your token has messaging access to more than one Messaging account on the number; with exactly one, Meta selects it |
Success response — note the wacid. prefix (WhatsApp Call ID, distinct from wamid. for messages):
{
"messaging_product": "whatsapp",
"calls": [
{ "id": "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA" }
]
}
biz_opaque_callback_data
An arbitrary string (up to 512 chars) that you pass into the call and that comes back unmodified in subsequent webhooks. Cloud API doesn't process it — it's purely for your own correlation (tying a call to a CRM record, an outbound campaign, etc.).
It's available on:
- The Call Connect webhook (BIC)
- The Call Terminate webhook (BIC and UIC if you accepted with one)
- The Call Status webhook for
RINGING/ACCEPTED/REJECTED
Set it on POST /calls with action: connect (BIC) or action: accept (UIC). It can't be added later.
Terminate a Call
POST /<PHONE_NUMBER_ID>/calls
{
"messaging_product": "whatsapp",
"call_id": "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",
"action": "terminate"
}
Always call terminate even if you sent an RTCP BYE in the media path — this ensures accurate billing. You don't need to call it when the user hangs up; you'll just receive the Call Terminate webhook.
If your token reaches more than one Messaging account on the number, send the same messaging_account_id on every request for the call, including terminate. Requests from a different Messaging account for a call that another Messaging account is handling are not processed.
Success response:
{ "success": true }
Call Connect Webhook (SDP Answer)
Arrives near-real-time after a successful POST /calls connect. Apply the SDP answer to your WebRTC stack to start media flow.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"field": "calls",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550001234",
"phone_number_id": "123456789012345"
},
"calls": [
{
"id": "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",
"to": "12015550123",
"to_user_id": "<BSUID>",
"to_parent_user_id": "<PARENT_BSUID>",
"from": "15550001234",
"event": "connect",
"direction": "BUSINESS_INITIATED",
"timestamp": "1749196895",
"biz_opaque_callback_data": "0fS5cePMok",
"session": {
"sdp_type": "answer",
"sdp": "<<RFC 8866 SDP>>"
}
}
],
"contacts": [
{
"profile": { "name": "<CALLEE_NAME>", "username": "<USERNAME>" },
"wa_id": "12015550123",
"user_id": "<BSUID>",
"parent_user_id": "<PARENT_BSUID>"
}
]
}
}
]
}
]
}
to_user_id and contacts[].user_id carry the user's BSUID. to and wa_id may be omitted when the user has adopted a username. to_parent_user_id and parent_user_id appear only if parent BSUIDs are enabled. The terminate webhook carries the same fields.
Call Status Webhook (RINGING / ACCEPTED / REJECTED)
Mirrors the messaging-status webhook envelope but with type: "call":
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"field": "calls",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550001234",
"phone_number_id": "123456789012345"
},
"statuses": [
{
"id": "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",
"type": "call",
"status": "ACCEPTED",
"timestamp": "1749197000",
"recipient_id": "12015550123",
"recipient_user_id": "<BSUID>",
"recipient_parent_user_id": "<PARENT_BSUID>",
"biz_opaque_callback_data": "0fS5cePMok"
}
]
}
}
]
}
]
}
status is one of RINGING, ACCEPTED, REJECTED. A REJECTED status is followed by a Call Terminate webhook. ACCEPTED typically arrives after media is already flowing. recipient_id may be omitted when the user has adopted a username; recipient_user_id carries the BSUID, and recipient_parent_user_id appears only if parent BSUIDs are enabled.
Call Terminate Webhook
Arrives whenever the call ends — user hangs up, you call action: terminate or action: reject, network failure, etc.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"field": "calls",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550001234",
"phone_number_id": "123456789012345"
},
"calls": [
{
"id": "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA",
"to": "12015550123",
"to_user_id": "<BSUID>",
"from": "15550001234",
"event": "terminate",
"direction": "BUSINESS_INITIATED",
"timestamp": "1749197480",
"status": "COMPLETED",
"start_time": "1749196900",
"end_time": "1749197480",
"duration": 580,
"biz_opaque_callback_data": "0fS5cePMok"
}
],
"contacts": [
{
"profile": { "name": "<CALLEE_NAME>" },
"wa_id": "12015550123",
"user_id": "<BSUID>"
}
]
}
}
]
}
]
}
| Field | Notes |
|---|---|
status | COMPLETED (ended without unexpected errors, including unanswered calls) or FAILED (didn't connect, or ended on an error) |
start_time, end_time, duration | Only present when the other party picked up, so an unanswered COMPLETED call has none. duration is in seconds. |
errors | Present only on failed calls with error information: code, message, href, error_data.details. See Troubleshooting → Calling Error Codes |
Limits
| Limit | Default |
|---|---|
| Quality-based call attempts per business phone number | By calling tier, rolling 24h (see above) |
| Connected BIC calls per business + user pair | 100 / 24h (sandbox: same) |
| Concurrent calls per phone number | 1,000 |
| Consecutive unanswered BIC calls before "reconsider" system message | 2 (sandbox: 5) |
| Consecutive unanswered BIC calls before permission auto-revoked | 4 (sandbox: 10) |
A connected call resets unanswered counters and call-permission-request rate limits between that business and that user.
Common Errors
| Code | Meaning | Fix |
|---|---|---|
138000 | Calling not enabled | Configure call settings (see Calling Configuration) |
138001 | Receiver uncallable (not on WhatsApp, hasn't accepted ToS, or unsupported client) | Confirm with recipient |
138002 | Concurrent calls limit (1,000) reached for the number | Retry later or reduce call volume |
138003 | Duplicate call — one is already ongoing with the receiver | Wait for current call to end |
138005 | Call rate limit exceeded | Reduce sending rate |
138006 | No approved call permission found | Send permission request first (Call Permissions) |
138012 | BIC daily limit hit (100 connected calls / 24h) | Wait for next-call timestamp in error_data |
138013 | BIC not available for this business phone number country | Check availability list |
138014 | Calling temporarily disabled (low quality) | Improve outreach quality, wait for restriction expiration |
138017 | Permission request can't be sent — permanent permission already exists | Just place the call directly |
138037 | Quality-based calling tier limit reached | Wait until earlier attempts leave the rolling 24-hour window |
138039 | Can't opt in to quality-based calling: number not eligible, or business-initiated calling recently restricted for quality | Read error_data.details; keep ALLOW_APPROVED_PERMISSION_ONLY until eligible |
Full error reference and SIP-specific errors are on Calling Troubleshooting.