# Business-Initiated Calls | Developer Documentation

<div id="bkmrk-business-initiated-c">## Business-Initiated Calls

<div><span>Updated: Nov 13, 2025</span></div><div id="bkmrk-overview"><div id="bkmrk-overview-1"><div>### Overview

</div></div></div><div>The Calling API supports making calls to WhatsApp users from your business.</div><div>The user dictates when calls can be received by [granting call permissions to the business phone number](/books/meta-whatsapp/page/obtain-user-call-permissions-developer-documentation).</div><div id="bkmrk-call-sequence-diagra"><div id="bkmrk-call-sequence-diagra-1"><div>#### Call sequence diagram

</div></div></div><div>![Business-initiated call sequence diagram showing flow between business, Cloud API, and WhatsApp user](https://support2.chatarchitect.com/uploads/images/gallery/2026-04/embedded-image-howb8bjk.jpeg)</div><div>*Note: The `ACCEPTED` call status webhook will typically arrive after the call has been established. The Cloud API primarily sends it for call event auditing.*</div><div id="bkmrk-prerequisites"><div id="bkmrk-prerequisites-1"><div>### Prerequisites

</div></div></div><div>Before you get started with business-initiated calling, ensure that:</div><span>[Subscribe](/books/meta-whatsapp/page/create-a-webhook-endpoint-developer-documentation) to the “calls” webhook field</span><span>[Calling APIs are enabled on your business phone number](/books/meta-whatsapp/page/configure-call-settings-developer-documentation)</span><div>Lastly, **before you can call a WhatsApp user, you must obtain their permission to do so.**</div><div>[Learn how to obtain WhatsApp user calling permissions here](/books/meta-whatsapp/page/obtain-user-call-permissions-developer-documentation)</div><div id="bkmrk-business-initiated-c-2"><div id="bkmrk-business-initiated-c-3"><div>### Business-initiated calling flow

</div></div></div><div id="bkmrk-part-1%3A-obtain-permi"><div id="bkmrk-part-1%3A-obtain-permi-1"><div>#### Part 1: Obtain permission to call the WhatsApp user

</div></div></div><div>You can obtain call permissions from the WhatsApp user in one of the following ways:</div><div id="bkmrk-send-a-call-permissi"><div id="bkmrk-send-a-call-permissi-1"><div>##### Send a call permission request message

</div></div></div><div>You can request call permissions by sending the WhatsApp user a permission request. Send it as a free form message during an open customer service window, or use a template message.</div><span>[Learn how to send a **free form** call permission request](/books/meta-whatsapp/page/obtain-user-call-permissions-developer-documentation)</span><span>[Learn how to send a **template** call permission request](/books/meta-whatsapp/page/obtain-user-call-permissions-developer-documentation)</span><div id="bkmrk-enable-callback_perm"><div id="bkmrk-enable-callback_perm-1"><div>##### Enable `callback_permission_status` in call settings

</div></div></div><div>When `callback_permission_status` is enabled, the user automatically provides call permission to your business when they place a call to you.</div><div>[Learn how to enable `callback_permission_status`](/books/meta-whatsapp/page/configure-call-settings-developer-documentation)</div><div id="bkmrk-whatsapp-user-grants"><div id="bkmrk-whatsapp-user-grants-1"><div>##### WhatsApp user grants permanent permissions

</div></div></div><div>The user can also grant permanent permissions to the business at any time through their business profile.</div><div id="bkmrk-part-2%3A-your-busines"><div id="bkmrk-part-2%3A-your-busines-1"><div>#### Part 2: Your business initiates a new call to the WhatsApp user

</div></div></div><div>Now that you have user permission, you can initiate a new call to the WhatsApp user in question.</div><div>If there are no errors, you will receive a successful response:</div><div>*Note: Response with error code `138006` indicates a lack of a call request permission for this business number from the WhatsApp user.*</div><div id="bkmrk-part-3%3A-you-establis"><div id="bkmrk-part-3%3A-you-establis-1"><div>#### Part 3: You establish the call connection using webhook signaling

</div></div></div><div>After you successfully initiate a new call, you receive a Call Connect webhook response containing an `SDP Answer` from Cloud API. Your business will then apply the `SDP Answer` from this webhook to your WebRTC stack to initiate the media connection.</div><div>You then receive an appropriate status webhook, indicating that the call is `RINGING`, `ACCEPTED`, or `REJECTED`:</div><div id="bkmrk-endpoints-for-busine"><div id="bkmrk-endpoints-for-busine-1"><div>### Endpoints for business-initiated calling

</div></div></div><div id="bkmrk-initiate-call"><div id="bkmrk-initiate-call-1"><div>#### Initiate call

</div></div></div><div>Use this endpoint to initiate a call to a WhatsApp user by providing a phone number and a WebRTC call offer. There is a rate limit of 10000 per 24 hours for initiating new calls per business phone number.</div><div id="bkmrk-body-parameters"><div id="bkmrk-body-parameters-1"><div>##### Body parameters

</div></div></div><div id="bkmrk-error-response"><div id="bkmrk-error-response-1"><div>##### Error response

</div></div></div><div>Possible errors that can occur:</div><span>Invalid `phone-number-id`</span><span>Permissions/Authorization errors</span><span>Request format validation errors, for example connection info, sdp, ice</span><span>SDP validation errors</span><span>Calling restriction errors</span><div>[View Calling API Error Codes and Troubleshooting for more information](/books/meta-whatsapp/page/troubleshoot-whatsapp-calling-errors-reference-guide-developer-documentation)</div><div>[View general Cloud API Error Codes here](/documentation/business-messaging/whatsapp/support/error-codes)</div><div id="bkmrk-terminate-call"><div id="bkmrk-terminate-call-1"><div>#### Terminate call

</div></div></div><div>Use this endpoint to terminate an active call.</div><div>This must be done even if there is an `RTCP BYE` packet in the media path. Ending the call this way also ensures pricing is more accurate.</div><div>When the WhatsApp user terminates the call, you do not have to call this endpoint. Once the call is successfully terminated, you will receive a [Call Terminate Webhook](/books/meta-whatsapp/page/business-initiated-calls-developer-documentation).</div><div id="bkmrk-body-parameters-3"><div id="bkmrk-body-parameters-4"><div>##### Body parameters

</div></div></div><div><table><thead><tr><th><span>Parameter </span></th><th><span>Description </span></th><th><span>Sample Value </span></th></tr></thead><tbody><tr><td><div><div>`call_id`</div><div>*String*</div></div></td><td><div><div>**Required**</div><div>  
The ID of the phone call.</div><div>For inbound calls, you receive a call ID from the [Call Connect webhook](/books/meta-whatsapp/page/business-initiated-calls-developer-documentation) when a WhatsApp user initiates the call.</div></div></td><td><div><div>`“wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh”`</div></div></td></tr><tr><td><div><div>`action`</div><div>*String*</div></div></td><td><div><div>**Required**</div><div>  
The action being taken on the given call ID.</div><div>Values can be `connect` | `pre_accept` | `accept` | `reject` | `terminate`</div></div></td><td><div><div>`“terminate”`</div></div></td></tr></tbody></table>

</div><div id="bkmrk-error-response-3"><div id="bkmrk-error-response-4"><div>##### Error response

</div></div></div><div>Possible errors that can occur:</div><span>Invalid `call id`</span><span>Invalid `phone-number-id`</span><span>The WhatsApp user has already terminated the call</span><span>Reject call is already in progress</span><span>Permissions/Authorization errors</span><div>[View Calling API Error Codes and Troubleshooting for more information](/books/meta-whatsapp/page/troubleshoot-whatsapp-calling-errors-reference-guide-developer-documentation)</div><div>[View general Cloud API Error Codes here](/documentation/business-messaging/whatsapp/support/error-codes)</div><div id="bkmrk-webhooks-for-busines"><div id="bkmrk-webhooks-for-busines-1"><div>### Webhooks for business-initiated calling

</div></div></div><div>With all Calling API webhooks, there is a `”calls”` object inside the `”value”` object of the webhook response. The `”calls”` object contains metadata about the call that is used to action on each call placed or received by your business.</div><div>To receive Calling API webhooks, subscribe to the “calls” webhook field.</div><div>[Learn more about Cloud API webhooks here](/books/meta-whatsapp/page/status-messages-webhook-reference-developer-documentation)</div><div id="bkmrk-call-status-webhook"><div id="bkmrk-call-status-webhook-1"><div>#### Call status webhook

</div></div></div><div>This webhook is sent during the following calling events:</div><span>Ringing: When the WhatsApp user’s client device begins ringing</span><span>Accepted: When the WhatsApp user accepts the call</span><span>Rejected: When the WhatsApp user rejects the call. You also receive the call terminate webhook in this case</span><div>The webhook structure here is similar to the Status webhooks used for the Cloud API messages.</div><div>[*Learn more about Cloud API status webhooks*](/books/meta-whatsapp/page/status-messages-webhook-reference-developer-documentation)</div><div id="bkmrk-webhook-values-for-%22-3"><div id="bkmrk-webhook-values-for-%22-4"><div>##### Webhook values for `"statuses"`

</div></div></div><div><table><thead><tr><th><span>Placeholder </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>`id`</div><div>*String*</div></div></td><td><div><div>A unique ID for the call</div></div></td></tr><tr><td><div><div>`timestamp`</div><div>*Integer*</div></div></td><td><div><div>The UNIX timestamp of the webhook event</div></div></td></tr><tr><td><div><div>`recipient_id`</div><div>*Integer*</div></div></td><td><div><div>The phone number of the WhatsApp user receiving the call</div></div></td></tr><tr><td><div><div>`status`</div><div>*Integer*</div></div></td><td><div><div>The current call status.</div><div>Possible values:</div><div>`RINGING`: Business initiated call is ringing the user</div><div>`ACCEPTED`: Business initiated call is accepted by the user</div><div>`REJECTED`: Business initiated call is rejected by the user</div></div></td></tr><tr><td><div><div>`biz_opaque_callback_data`</div><div>*String*</div></div></td><td><div><div>Arbitrary string your business passes into the call for tracking and logging purposes.</div><div>Will only be returned if provided through [Initiate New Call API requests](/books/meta-whatsapp/page/business-initiated-calls-developer-documentation)</div></div></td></tr></tbody></table>

</div><div id="bkmrk-call-terminate-webho"><div id="bkmrk-call-terminate-webho-1"><div>#### Call terminate webhook

</div></div></div><div>A webhook notification is sent whenever the call has been terminated for any reason, such as when the WhatsApp user hangs up, or when the business calls the endpoint with an action of `terminate` or `reject`.</div><div id="bkmrk-webhook-values-for-%22-6"><div id="bkmrk-webhook-values-for-%22-7"><div>##### Webhook values for `"calls"`

</div></div></div><div><table><thead><tr><th><span>Placeholder </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>`id`</div><div>*String*</div></div></td><td><div><div>A unique ID for the call</div></div></td></tr><tr><td><div><div>`to`</div><div>*Integer*</div></div></td><td><div><div>The number being called (callee)</div></div></td></tr><tr><td><div><div>`from`</div><div>*Integer*</div></div></td><td><div><div>The number of the caller</div></div></td></tr><tr><td><div><div>`event`</div><div>*Integer*</div></div></td><td><div><div>The calling event that this webhook is notifying the subscriber of</div></div></td></tr><tr><td><div><div>`timestamp`</div><div>*Integer*</div></div></td><td><div><div>The UNIX timestamp of the webhook event</div></div></td></tr><tr><td><div><div>`direction`</div><div>*String*</div></div></td><td><div><div>The direction of the call being made.</div><div>Can contain either:</div><div>`BUSINESS_INITIATED`, for calls initiated by your business.</div><div>`USER_INITIATED`, for calls initiated by a WhatsApp user.</div></div></td></tr><tr><td><div><div>`start_time`</div><div>*Integer*</div></div></td><td><div><div>The UNIX timestamp of when the call started.</div><div>Only present when the call was picked up by the other party.</div></div></td></tr><tr><td><div><div>`end_time`</div><div>*Integer*</div></div></td><td><div><div>The UNIX timestamp of when the call ended.</div><div>Only present when the call was picked up by the other party.</div></div></td></tr><tr><td><div><div>`duration`</div><div>*Integer*</div></div></td><td><div><div>Duration of the call in seconds.</div><div>Only present when the call was picked up by the other party.</div></div></td></tr><tr><td><div><div>`biz_opaque_callback_data`</div><div>*String*</div></div></td><td><div><div>Arbitrary string your business passes into the call for tracking and logging purposes.</div><div>Will only be returned if provided through an [Initiate Call API request](/books/meta-whatsapp/page/business-initiated-calls-developer-documentation) or [Accept Call request](/books/meta-whatsapp/page/api-and-webhook-reference-developer-documentation)</div></div></td></tr><tr><td><div><div>`errors.code`</div><div>*Integer*</div></div></td><td><div><div>The `errors` object is present only for failed calls when there is error information available. Code is one of the [calling error codes](/books/meta-whatsapp/page/troubleshoot-whatsapp-calling-errors-reference-guide-developer-documentation)</div></div></td></tr></tbody></table>

</div><div id="bkmrk-sdp-overview-and-sam"><div id="bkmrk-sdp-overview-and-sam-1"><div>### SDP overview and sample structures

</div></div></div><div>Session Description Protocol (SDP) is a text-based format used to describe the characteristics of multimedia sessions, such as voice and video calls, in real-time communication applications. SDP provides a standardized way to describe the session’s media streams. This includes media type, codecs, protocols, and parameters for establishing and managing the session.</div><div>In the context of WebRTC, SDP is used to negotiate the media parameters between the sender and receiver, enabling them to agree on the specifics of the media exchange.</div><div>[View SDP sample structures for business-initiated calls](/books/meta-whatsapp/page/api-and-webhook-reference-developer-documentation)</div></div>