Business-Initiated Calls

Place outbound voice calls to WhatsApp users. POST /calls with action: connect, SDP offer/answer flow, call status webhooks (RINGING/ACCEPTED/REJECTED), terminate webhook with duration, biz_opaque_callback_data tracking.

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:

TierCall attempts per rolling 24 hours
CALLING_TIER_NO_ACCESSQuality-based calling unavailable
CALLING_TIER_1K1,000
CALLING_TIER_15K15,000
CALLING_TIER_UNLIMITEDNo 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_UPDATE event on the account_update webhook.
  • 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_mode setting. Opting in when the number isn't eligible returns 138039.

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 calls webhook field.
  • Calling enabled on the business phone number (see Calling Configuration).
  • Approved call permission from the recipient (error 138006 if 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

  1. Obtain permission. Send a call permission request (free-form or template) and wait for the user to accept, rely on callback_permission_status: ENABLED to 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.
  2. POST /calls with action: connect and an SDP offer from your WebRTC stack.
  3. 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, or REJECTED status webhooks.
  4. 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"
}
FieldNotes
toRecipient WhatsApp user phone number. Required unless you send recipient.
recipientOptional. The user's BSUID or parent BSUID, instead of or in addition to to. If you send both, to takes precedence.
actionconnect for new calls. Other values: pre_accept, accept, reject, terminate (used for user-initiated calls)
session.sdp_typeoffer for BIC
session.sdpRFC 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_dataOptional. Up to 512 chars. Echoed back in subsequent webhooks for tracking
recording / transcriptionOptional. Opt this call into recording or transcription. See Call Recording & Transcription
messaging_account_idOptional. 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>"
              }
            ]
          }
        }
      ]
    }
  ]
}
FieldNotes
statusCOMPLETED (ended without unexpected errors, including unanswered calls) or FAILED (didn't connect, or ended on an error)
start_time, end_time, durationOnly present when the other party picked up, so an unanswered COMPLETED call has none. duration is in seconds.
errorsPresent only on failed calls with error information: code, message, href, error_data.details. See Troubleshooting → Calling Error Codes

Limits

LimitDefault
Quality-based call attempts per business phone numberBy calling tier, rolling 24h (see above)
Connected BIC calls per business + user pair100 / 24h (sandbox: same)
Concurrent calls per phone number1,000
Consecutive unanswered BIC calls before "reconsider" system message2 (sandbox: 5)
Consecutive unanswered BIC calls before permission auto-revoked4 (sandbox: 10)

A connected call resets unanswered counters and call-permission-request rate limits between that business and that user.

Common Errors

CodeMeaningFix
138000Calling not enabledConfigure call settings (see Calling Configuration)
138001Receiver uncallable (not on WhatsApp, hasn't accepted ToS, or unsupported client)Confirm with recipient
138002Concurrent calls limit (1,000) reached for the numberRetry later or reduce call volume
138003Duplicate call — one is already ongoing with the receiverWait for current call to end
138005Call rate limit exceededReduce sending rate
138006No approved call permission foundSend permission request first (Call Permissions)
138012BIC daily limit hit (100 connected calls / 24h)Wait for next-call timestamp in error_data
138013BIC not available for this business phone number countryCheck availability list
138014Calling temporarily disabled (low quality)Improve outreach quality, wait for restriction expiration
138017Permission request can't be sent — permanent permission already existsJust place the call directly
138037Quality-based calling tier limit reachedWait until earlier attempts leave the rolling 24-hour window
138039Can't opt in to quality-based calling: number not eligible, or business-initiated calling recently restricted for qualityRead error_data.details; keep ALLOW_APPROVED_PERMISSION_ONLY until eligible

Full error reference and SIP-specific errors are on Calling Troubleshooting.

Related

  • Cloud API CallingVoice calling on WhatsApp Business Cloud API: VoIP via WebRTC or SIP, business-initiated and user-initiated calls, prerequisites, availability, and integration patterns.
  • Call PermissionsObtain permission to call WhatsApp users: temporary (7-day) and permanent permissions, three ways to obtain (free-form request, template request, callback auto-prompt, business profile), get permission state endpoint, permission reply webhook.
  • Call Buttons & Deep LinksDrive WhatsApp calls from messages and links: voice_call interactive messages, voice_call template buttons, wa.me/call/<number> deep links with biz_payload tracking.
  • Calling PricingHow Meta bills WhatsApp Calling: free user-initiated calls, per-pulse business-initiated billing, volume tiers, customer service window interaction, call permission request charges, billing prerequisites.
  • Calling TroubleshootingWhatsApp Calling errors and fixes: full error code table (138000-138023), SIP-specific status codes, media-flow timeouts, audio clipping causes and mitigations (SDES, pre-accept), quick triage guide.
Browse more docsStart Free Trial