Cloud API Calling

Voice calling on WhatsApp Business Cloud API: VoIP via WebRTC or SIP, business-initiated and user-initiated calls, prerequisites, availability, and integration patterns.

What Cloud API Calling Is

The WhatsApp Business Calling API lets your business initiate and receive voice calls with WhatsApp users over VoIP, using the same business phone number you use for messaging. Calls go through Meta Cloud API and use WebRTC for media — encrypted with SRTP/DTLS, audio compressed with OPUS by default.

The same business phone number unifies messaging and calling. From the user's perspective, it's a familiar WhatsApp call — no separate app, no SMS-style trust prompts, no region-specific carrier limitations.

Calling is not enabled by default. You opt in per phone number by configuring call settings (see Calling Configuration).

Calling Pages in This Section

  • Calling Configuration — Enable calling, call hours, holiday schedule, callback permissions, audio codecs, voicemail, calling restrictions, settings webhooks
  • Business-Initiated Calls — Place outbound calls; /calls endpoint with connect/terminate; lifecycle webhooks
  • User-Initiated Calls — Receive inbound calls; pre_accept/accept/reject/terminate; DTMF; companion-device support
  • Call Permissions — Temporary vs permanent permissions; three ways to obtain them; permission-reply webhooks
  • SIP Configuration — Use SIP signaling instead of Graph API + webhooks; digest auth; SDES vs DTLS
  • Call Buttons & Deep Links — voice_call interactive messages, template buttons, wa.me/call/<number> deep links
  • Call Recording & Transcription — Per-call recording and transcription objects, announcements, recording and transcript webhooks, 7-day retention
  • API Reference — Consolidated endpoints + webhook reference + WebRTC/media implementation guidelines
  • Pricing — Per-pulse billing, volume tiers, CSW interaction with calling
  • Troubleshooting — Error codes, audio clipping, media-flow timeouts

Two Call Paths: User-Initiated vs Business-Initiated

User-Initiated (UIC)Business-Initiated (BIC)
Who places the callWhatsApp userYour business
Permission requiredNo (subject to call hours and call_icon_visibility)Yes, explicit user permission first, except on quality-based numbers (Colombia, Mexico) unless the user declined or revoked it
AvailabilityEvery country where Cloud API is availableAll countries except USA, Canada, Egypt, Vietnam, Nigeria (business phone number country)
PricingFreePer-pulse billed (see Pricing)
First webhookconnect with SDP offerNone — your business places the call via API; you get a connect with SDP answer

The business phone number's country code must be in the BIC-supported list. The recipient's phone can be in any country where Cloud API is available.

Two Signaling Paths: Graph API vs SIP

ConfigurationSignalingMedia
Default (after enabling calling)Graph API endpoints + webhooks (HTTPS)WebRTC: ICE + DTLS + SRTP, OPUS codec
SIP with WebRTC mediaSIP over TLSWebRTC: ICE + DTLS + SRTP, OPUS codec
SIP with SDES mediaSIP over TLSSRTP with SDES key exchange (no ICE/DTLS), OPUS

OPUS is the default codec everywhere; PCMA/PCMU (G.711) can be added in any configuration via audio.additional_codecs. SDES can also replace ICE + DTLS with Graph API + webhook signaling, not only with SIP.

When SIP is enabled, calling-related Graph API endpoints stop working and calling webhooks are not sent unless you opt in to SIP call webhooks — SIP becomes the exclusive signaling path. Messaging continues to use Graph API + webhooks normally.

Pick Graph API + webhooks unless you have a SIP-based contact center or telephony infrastructure that needs native SIP integration. See SIP Configuration for details.

Prerequisites

Before enabling calling on a business phone number:

  • The number must be in use with Cloud API (not the WhatsApp Business app).
  • Subscribe your app to the calls webhook field (with SIP, only needed if you enable SIP call webhooks).
  • The same app must be subscribed to the WABA of your business phone number.
  • The app must have whatsapp_business_messaging permission for the number.
  • The business must have a daily messaging limit of at least 2,000 unique recipients. (Test numbers and sandbox accounts bypass this.)
  • A valid payment method must be attached to the WABA — calls require billing on file even though UIC is free.
  • Business verification is not required for calling (same as messaging).

Availability

User-initiated calling: every country where Cloud API is available. iOS, Android, and selected companion devices (iPhone/Android phones registered as additional devices on the same account). Not supported on WhatsApp Web or WhatsApp Desktop.

Business-initiated calling: every country where Cloud API is available except the following business-phone-number countries:

  • United States
  • Canada
  • Egypt
  • Vietnam
  • Nigeria

The recipient's phone can be from any country where Cloud API is available.

Testing and Sandbox

Public test numbers (PTNs) and Sandbox accounts have relaxed calling limits to make integration easier. Sandbox accounts are only available to Tech Partners.

LimitProductionSandbox / PTN
Call permission requests per day (per pair)125
Call permission requests per 7 days (per pair)2100
Consecutive unanswered calls before "reconsider" system message25
Consecutive unanswered calls before permission auto-revoked410
Connected calls per 24 hours on approved permissions100100
Temporary permission duration after the user approves7 days7 days

To test calling in a sandbox, claim the sandbox account with the Cloud API and Calling feature (App Dashboard, WhatsApp, Partner Tools). A sandbox claimed with another feature has no calling setup, and you can hold only one sandbox at a time, so delete the old one and claim a new one. If Cloud API and Calling is missing from the Features dropdown, the calling sandbox is not enabled for your business yet.

A sandbox test number only exchanges messages and calls with the phone numbers on its recipient list (up to 5, added in Partner Tools with a verification code). Messages and business-initiated calls to any other number fail with 131030. To test business-initiated calls, also grant permission on the test device: open the chat with the sandbox number, tap its name, then Business Calling Permission → Allow calls.

Test numbers also bypass the 2,000-message-limit prerequisite for enabling calling. Calling is disabled by default on test numbers — you must configure call settings before placing or receiving calls.

Integration Patterns

How you wire up calling depends on your role:

PatternNumber setupNotes
Messaging partner capable of callingExisting messaging number extended, or a new numberThe messaging partner reuses its app and subscribes it to the calls webhook field (a separate calling app is possible but not recommended). The business keeps paying that partner, who now bills for calling too.
WhatsApp account model evolution (Meta's recommendation)Single number, operated independently by a messaging partner and a calling partner, each with its own line of creditThe messaging partner keeps its existing app and integration. The calling partner hosts Embedded Signup, through which the business shares its existing WhatsApp account and number, then handles calls webhooks and calling Graph API requests. The same number serves messaging and calling.
Exclusive calling partnerNew number for callingNo messaging partner. The calling partner hosts Embedded Signup pointing to its own app. Meta bills the business directly (a direct payment relationship can take several weeks to set up) unless the calling partner extends its credit line.

Meta's terms forbid PSTN on any leg of a WhatsApp call. SIP trunks are allowed if they stay exclusively VoIP — bridging into the PSTN is prohibited.

Single App vs Multiple Apps

You can almost always reuse your existing messaging app for calling. The webhook callback URL is the same; the payload distinguishes message events from call events.

Reasons to use one app:

  • Less app-review and ongoing maintenance overhead.
  • Simpler footprint on Meta.
  • The Embedded Signup app and the Graph-API-invoking app stay equal.

If you do want separate apps, you can — subscribe the calling app only to calls-related fields and the messaging app only to message-related fields. Override the callback URL per app at WABA or phone-number level. The trade-off is operational complexity, especially for permission management.

Dualhook's Stance on Calling

Dualhook does not currently expose calling features in its dashboard. Calling is sender-side and media-heavy — your backend handles SDP, WebRTC stacks, and call-state machines, just as you handle outbound messaging today.

What Dualhook does affect:

  • The encrypted authorization created through Embedded Signup includes whatsapp_business_messaging, which is the same permission needed to place calls and accept inbound calls. Dualhook does not reveal that credential. The Runtime API accepts basic calling settings on Cloud API connections, but it has no /calls route and rejects SIP configuration, so placing or answering calls and SIP need your own Meta app with access to the number.
  • The Calling API, including SIP, is not available on Coexistence numbers, which most Dualhook connections are. Voice and video calls stay in the WhatsApp Business app.
  • Dualhook's Meta app does not subscribe to the calls webhook field, so a Dualhook connection delivers no call webhooks and Dualhook does not ingest them. Subscribe your own Meta app to calls to receive them on that app's callback.
  • Dualhook does not auto-subscribe to account_settings_update either. To receive the calling-settings webhook, subscribe your own app to that field at the WABA level — see Calling Configuration.

If you want Dualhook to surface calling-related state (permission status, call hours, call analytics) in the dashboard, that's a feature request — open it through the in-app support chat.

Related

  • Calling ConfigurationEnable calling on a business phone number, configure call hours and holidays, restrict the call icon by country, set callback permissions, choose audio codecs, set up voicemail, handle calling restrictions, listen for settings webhooks.
  • Business-Initiated CallsPlace 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.
  • User-Initiated CallsReceive inbound voice calls from WhatsApp users. Call Connect webhook with SDP offer, pre-accept for faster setup, accept/reject/terminate actions, DTMF dial pad, companion-device support.
  • 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.
  • 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.
Browse more docsStart Free Trial