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;
/callsendpoint withconnect/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_callinteractive messages, template buttons,wa.me/call/<number>deep links - Call Recording & Transcription — Per-call
recordingandtranscriptionobjects, 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 call | WhatsApp user | Your business |
| Permission required | No (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 |
| Availability | Every country where Cloud API is available | All countries except USA, Canada, Egypt, Vietnam, Nigeria (business phone number country) |
| Pricing | Free | Per-pulse billed (see Pricing) |
| First webhook | connect with SDP offer | None — 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
| Configuration | Signaling | Media |
|---|---|---|
| Default (after enabling calling) | Graph API endpoints + webhooks (HTTPS) | WebRTC: ICE + DTLS + SRTP, OPUS codec |
| SIP with WebRTC media | SIP over TLS | WebRTC: ICE + DTLS + SRTP, OPUS codec |
| SIP with SDES media | SIP over TLS | SRTP 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
callswebhook 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_messagingpermission 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.
| Limit | Production | Sandbox / PTN |
|---|---|---|
| Call permission requests per day (per pair) | 1 | 25 |
| Call permission requests per 7 days (per pair) | 2 | 100 |
| Consecutive unanswered calls before "reconsider" system message | 2 | 5 |
| Consecutive unanswered calls before permission auto-revoked | 4 | 10 |
| Connected calls per 24 hours on approved permissions | 100 | 100 |
| Temporary permission duration after the user approves | 7 days | 7 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:
| Pattern | Number setup | Notes |
|---|---|---|
| Messaging partner capable of calling | Existing messaging number extended, or a new number | The 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 credit | The 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 partner | New number for calling | No 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/callsroute 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
callswebhook field, so a Dualhook connection delivers no call webhooks and Dualhook does not ingest them. Subscribe your own Meta app tocallsto receive them on that app's callback. - Dualhook does not auto-subscribe to
account_settings_updateeither. 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.