# WhatsApp Cloud API - Calling API | Developer Documentation

<div id="bkmrk-whatsapp-cloud-api--"><div><div>## WhatsApp Cloud API - Calling API

<div><div><div><span>Copy for LLM</span></div></div><div>[<span>View as Markdown</span>](/books/meta-whatsapp/page/whatsapp-cloud-api-calling-api-developer-documentation)</div></div></div><div><div>Version</div></div><div><div><div><div><div><div><span><span>The WhatsApp Business Calling API enables you to initiate and receive calls with users on WhatsApp using voice-over-internet protocol (VoIP).</span></span></div></div></div></div></div></div></div><div><div>---

<div><div><div id="bkmrk-get-%2F%7Bversion%7D%2F%7Bphon"><div id="bkmrk-get-%2F%7Bversion%7D%2F%7Bphon-1"><div>### GET /{Version}/{Phone-Number-ID}/call\_permissions

</div></div></div><div><div><div><div><div><div><span><span>Check whether you have permission to call a WhatsApp user and what actions are available. This endpoint returns the current permission status for calling a specific user, along with available actions and their limits.</span></span></div></div><div><div><span><span>Permission Status:</span></span></div></div><div>`<span><span>granted</span></span>`<span><span>: You have active permission to call this user - </span></span>`<span><span>pending</span></span>`<span><span>: A permission request has been sent but not yet approved - </span></span>`<span><span>denied</span></span>`<span><span>: The user has denied call permissions - </span></span>`<span><span>expired</span></span>`<span><span>: Previous permission has expired</span></span></div><div><div><span><span>Available Actions:</span></span></div></div><div>`<span><span>start_call</span></span>`<span><span>: Initiate a new call to this user - </span></span>`<span><span>send_call_permission_request</span></span>`<span><span>: Send a permission request to this user</span></span></div><div><div><span><span>Error Handling:</span></span></div></div><div><div><span><span>This endpoint may return various error codes including rate limiting errors if too many permission checks are made within a short period.</span></span></div></div></div></div></div></div>#### Request Syntax

<div><div><div><div><div><div><span>Try it</span></div></div></div></div></div></div><div><div><div><div><div><div><div>Select language</div></div></div></div>---

</div><div><div><div><div><div><div>Select status code</div></div></div></div>---

</div></div></div></div><div><span>Header Parameters</span>---

<div><div><span>User-Agent</span><span>string</span></div><div><div><div><div><div><div><span><span>The user agent string identifying the client software making the request.</span></span></div></div></div></div></div></div></div><div><div><span>Authorization</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.</span></span></div></div></div></div></div></div></div><div><div><span>Content-Type</span><span>One of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"</span><span>·</span><span>required</span></div></div></div><div><span>Path Parameters</span>---

<div><div><span>Version</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>The API version to use</span></span></div></div></div></div></div></div></div><div><div><span>Phone-Number-ID</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>The ID of the phone number registered with your WhatsApp Business Account</span></span></div></div></div></div></div></div></div></div><div><span>Query Parameters</span>---

<div><div><span>user\_wa\_id</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>The WhatsApp ID of the user you want to check call permissions for</span></span></div></div></div></div></div></div></div></div><div><span>Responses</span>---

<div><div><div><div><div><div><span><span>Check whether you have permission to call a WhatsApp user and what actions are available. This endpoint returns the current permission status for calling a specific user, along with available actions and their limits.</span></span></div></div><div><div><span><span>Permission Status:</span></span></div></div><div>`<span><span>granted</span></span>`<span><span>: You have active permission to call this user - </span></span>`<span><span>pending</span></span>`<span><span>: A permission request has been sent but not yet approved - </span></span>`<span><span>denied</span></span>`<span><span>: The user has denied call permissions - </span></span>`<span><span>expired</span></span>`<span><span>: Previous permission has expired</span></span></div><div><div><span><span>Available Actions:</span></span></div></div><div>`<span><span>start_call</span></span>`<span><span>: Initiate a new call to this user - </span></span>`<span><span>send_call_permission_request</span></span>`<span><span>: Send a permission request to this user</span></span></div><div><div><span><span>Error Handling:</span></span></div></div><div><div><span><span>This endpoint may return various error codes including rate limiting errors if too many permission checks are made within a short period.</span></span></div></div></div></div></div></div><div><span>200</span><div><div><div><div><div><div><span><span>Call Permissions Check Success</span></span></div></div></div></div></div></div><div><div><span>Content Type: </span><span>application/json</span></div><div><div><span>Schema: </span><span>CallPermissionCheckResponsePayload</span></div><div><div><div id="bkmrk-show-child-attribute"><div><span>Show child attributes</span></div></div><div id="bkmrk-callpermissioncheckr"><div>---

<div><span>CallPermissionCheckResponsePayload</span></div><div>---

<div><div><span>messaging\_product</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Messaging product</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>permission</span><span>object</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Call permission details</span></span></div></div></div></div></div></div></div><div><div><div id="bkmrk-show-child-attribute-1"><div><span>Show child attributes</span></div></div><div id="bkmrk-statusone-of-%22grante"><div><div>---

<div><div><span>status</span><span>One of "granted", "pending", "denied", "expired"</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Current permission status for calling this user</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>expiration\_time</span><span>integer (int64)</span></div><div><div><div><div><div><div><span><span>Unix timestamp when the permission expires (if applicable)</span></span></div></div></div></div></div></div></div></div></div></div></div></div></div><div>---

<div><div><span>actions</span><span>array of object</span></div><div><div><div><div><div><div><span><span>Available actions and their restrictions</span></span></div></div></div></div></div></div></div><div><div><div id="bkmrk-show-child-attribute-2"><div><span>Show child attributes</span></div></div><div id="bkmrk-actions%5B%5Dobjectshow-"><div><div>---

<div><div><span>actions\[\]</span><span>object</span></div></div><div><div><div id="bkmrk-show-child-attribute-3"><div><span>Show child attributes</span></div></div><div id="bkmrk-action_nameone-of-%22s"><div><div>---

<div><div><span>action\_name</span><span>One of "start\_call", "send\_call\_permission\_request"</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Name of the action</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>can\_perform\_action</span><span>boolean</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Whether the business can perform this action</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>limits</span><span>array of object</span></div><div><div><div><div><div><div><span><span>Rate limits for this action</span></span></div></div></div></div></div></div></div><div><div><div id="bkmrk-show-child-attribute-4"><div><span>Show child attributes</span></div></div><div id="bkmrk-limits%5B%5Dobjectshow-c"><div><div>---

<div><div><span>limits\[\]</span><span>object</span></div></div><div><div><div id="bkmrk-show-child-attribute-5"><div><span>Show child attributes</span></div></div><div id="bkmrk-time_periodstring%C2%B7re"><div><div>---

<div><div><span>time\_period</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Time period for the limit</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>current\_usage</span><span>integer</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Current usage count</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>max\_allowed</span><span>integer</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Maximum allowed usage</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>limit\_expiration\_time</span><span>integer (int64)</span></div><div><div><div><div><div><div><span><span>Unix timestamp when the limit resets</span></span></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div><div><span>400</span><div><div><div><div><div><div><span><span>Bad Request - Invalid request parameters</span></span></div></div></div></div></div></div><div><div><span>Content Type: </span><span>application/json</span></div></div></div><div><span>429</span><div><div><div><div><div><div><span><span>Too Many Requests - Rate limit exceeded</span></span></div></div></div></div></div></div><div><div><span>Content Type: </span><span>application/json</span></div></div></div><div><span>403</span><div><div><div><div><div><div><span><span>Forbidden - Template not approved or insufficient permissions</span></span></div></div></div></div></div></div><div><div><span>Content Type: </span><span>application/json</span></div></div></div><div><span>500</span><div><div><div><div><div><div><span><span>Internal Server Error - An unexpected error occurred</span></span></div></div></div></div></div></div><div><div><span>Content Type: </span><span>application/json</span></div></div></div></div></div><div><div><div><div><div><div><div>Select language</div></div></div></div>---

</div><div><div><div><div><div><div>Select status code</div></div></div></div>---

</div></div></div></div></div></div><div>---

<div><div><div id="bkmrk-post-%2F%7Bversion%7D%2F%7Bpho"><div id="bkmrk-post-%2F%7Bversion%7D%2F%7Bpho-1"><div>### POST /{Version}/{Phone-Number-ID}/calls

</div></div></div><div><div><div><div><div><div><span><span>Use this endpoint to initiate, accept, reject, or terminate WhatsApp calls.</span></span></div></div><div><div><span><span>For initiating or managing a call:</span></span></div></div><div><div><span><span>Send a POST request with the appropriate action (connect, pre\_accept, accept, reject, terminate).</span></span></div></div><div><div><span><span>For terminating a call:</span></span></div></div><div><div><span><span>Send a POST request with action "terminate" and the call\_id.</span></span></div></div><div><div><span><span>Note:</span></span><span><span> Response with error code 138006 indicates a lack of a call request permission for this business number from the WhatsApp user.</span></span></div></div></div></div></div></div>#### Request Syntax

<div><div><div><div><div><div><span>Try it</span></div></div></div></div></div></div><div><div><div><div><div><div><div>Select language</div></div></div></div>---

</div><div><div><div><div><div><div>Select status code</div></div></div></div>---

</div></div></div></div><div><span>Header Parameters</span>---

<div><div><span>User-Agent</span><span>string</span></div><div><div><div><div><div><div><span><span>The user agent string identifying the client software making the request.</span></span></div></div></div></div></div></div></div><div><div><span>Authorization</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.</span></span></div></div></div></div></div></div></div><div><div><span>Content-Type</span><span>One of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"</span><span>·</span><span>required</span></div></div></div><div><span>Path Parameters</span>---

<div><div><span>Version</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>The API version to use</span></span></div></div></div></div></div></div></div><div><div><span>Phone-Number-ID</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>The ID of the phone number registered with your WhatsApp Business Account</span></span></div></div></div></div></div></div></div></div><div><span>Optional</span>---

<div><div><span>Content Type: </span><span>application/json</span></div><div><div><span>Schema: </span><span>Must be one of: CallRequestPayload, CallTerminateRequestPayload</span></div><div><div><div id="bkmrk-show-child-attribute-6"><div><span>Show child attributes</span></div></div><div id="bkmrk-must-be-one-of%3A-call"><div>---

<div><span>Must be one of: CallRequestPayload, CallTerminateRequestPayload</span></div><div>---

<div><div><span>CallRequestPayload</span></div></div><div><div><div id="bkmrk-show-child-attribute-7"><div><span>Show child attributes</span></div></div><div id="bkmrk-messaging_productstr"><div><div>---

<div><div><span>messaging\_product</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Messaging product</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>to</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>The number being called (callee)</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>action</span><span>One of "connect", "pre\_accept", "accept", "reject", "terminate"</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>The action being taken on the given call ID</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>session</span><span>object</span></div><div><div><div><div><div><div><span><span>Contains the session description protocol (SDP) type and description language</span></span></div></div></div></div></div></div></div><div><div><div id="bkmrk-show-child-attribute-8"><div><span>Show child attributes</span></div></div><div id="bkmrk-sdp_typeone-of-%22offe"><div><div>---

<div><div><span>sdp\_type</span><span>One of "offer", "answer"</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>SDP type - "offer" for connect action, "answer" for accept action</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>sdp</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>The SDP info of the device on the other end of the call. The SDP must be compliant with RFC 8866</span></span></div></div></div></div></div></div></div></div></div></div></div></div></div><div>---

<div><div><span>biz\_opaque\_callback\_data</span><span>string</span></div></div></div></div></div></div></div></div><div>---

<div><div><span>CallTerminateRequestPayload</span></div></div><div><div><div id="bkmrk-show-child-attribute-9"><div><span>Show child attributes</span></div></div><div id="bkmrk-messaging_productstr-1"><div><div>---

<div><div><span>messaging\_product</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Messaging product</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>call\_id</span><span>string</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>The WhatsApp call ID</span></span></div></div></div></div></div></div></div></div><div>---

<div><div><span>action</span><span>"terminate"</span><span>·</span><span>required</span></div><div><div><div><div><div><div><span><span>Action to terminate the call</span></span></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div><div><span>Responses</span>---

<div><div><div><div><div><div><span><span>Use this endpoint to initiate, accept, reject, or terminate WhatsApp calls.</span></span></div></div><div><div><span><span>For initiating or managing a call:</span></span></div></div><div><div><span><span>Send a POST request with the appropriate action (connect, pre\_accept, accept, reject, terminate).</span></span></div></div><div><div><span><span>For terminating a call:</span></span></div></div><div><div><span><span>Send a POST request with action "terminate" and the call\_id.</span></span></div></div><div><div><span><span>Note:</span></span><span><span> Response with error code 138006 indicates a lack of a call request permission for this business number from the WhatsApp user.</span></span></div></div></div></div></div></div><div><span>200</span><div><div><div><div><div><div><span><span>Call Management Success</span></span></div></div></div></div></div></div><div><div><span>Content Type: </span><span>application/json</span></div><div><div><span>Schema: </span><span>Must be one of: CallResponsePayload, CallTerminateResponsePayload</span></div><div><div><div id="bkmrk-show-child-attribute-10"><div><span>Show child attributes</span></div></div><div id="bkmrk-must-be-one-of%3A-call-1"><div>---

<div><span>Must be one of: CallResponsePayload, CallTerminateResponsePayload</span></div><div>---

<div><div><span>CallResponsePayload</span></div></div><div><div><div id="bkmrk-show-child-attribute-11"><div><span>Show child attributes</span></div></div><div id="bkmrk-messaging_productstr-2"><div><div>---

<div><div><span>messaging\_product</span><span>string</span></div></div></div><div>---

<div><div><span>calls</span><span>array of object</span></div></div><div><div><div id="bkmrk-show-child-attribute-12"><div><span>Show child attributes</span></div></div><div id="bkmrk-calls%5B%5Dobjectshow-ch"><div><div>---

<div><div><span>calls\[\]</span><span>object</span></div></div><div><div><div id="bkmrk-show-child-attribute-13"><div><span>Show child attributes</span></div></div><div id="bkmrk-idstring"><div><div>---

<div><div><span>id</span><span>string</span></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div><div>---

<div><div><span>CallTerminateResponsePayload</span></div></div><div><div><div id="bkmrk-show-child-attribute-14"><div><span>Show child attributes</span></div></div><div id="bkmrk-successboolean"><div><div>---

<div><div><span>success</span><span>boolean</span></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div><div><div><div><div><div><div><div>Select language</div></div></div></div>---

</div><div><div><div><div><div><div>Select status code</div></div></div></div>---

</div></div></div></div></div></div></div><div><div id="bkmrk-authentication"><div id="bkmrk-authentication-1"><div>### Authentication

</div></div></div><div><table><tbody><tr><td><div>**Scheme**</div></td><td><div>**Type**</div></td><td><div>**Location**</div></td></tr><tr><td><div><div><div><div><div><div><div><span><span>bearerAuth</span></span></div></div></div></div></div></div></div></td><td><div><div><div><div><div><div><div><span><span>HTTP Bearer</span></span></div></div></div></div></div></div></div></td><td><div><div><div><div><div><div><div><span><span>Header: </span></span>`<span><span>Authorization</span></span>`</div></div></div></div></div></div></div></td></tr></tbody></table>

</div><div>#### Usage Examples

<div><span>bearerAuth:</span><div><div><div><div><div><div><span><span>Include </span></span>`<span><span>Authorization: Bearer your-token-here</span></span>`<span><span> in request headers</span></span></div></div></div></div></div></div></div></div><div>#### Global Authentication Requirements

<div><span>All endpoints require:</span><div><div><div><div><div><div><span><span>bearerAuth</span></span></div></div></div></div></div></div></div></div></div></div>