Skip to main content

WhatsApp Cloud API - Calling API | Developer Documentation

WhatsApp Cloud API - Calling API

Copy for LLM
Version
The WhatsApp Business Calling API enables you to initiate and receive calls with users on WhatsApp using voice-over-internet protocol (VoIP).

GET /{Version}/{Phone-Number-ID}/call_permissions

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.
Permission Status:
granted: You have active permission to call this user - pending: A permission request has been sent but not yet approved - denied: The user has denied call permissions - expired: Previous permission has expired
Available Actions:
start_call: Initiate a new call to this user - send_call_permission_request: Send a permission request to this user
Error Handling:
This endpoint may return various error codes including rate limiting errors if too many permission checks are made within a short period.

Request Syntax

Try it
Select language
Select status code
Header Parameters
User-Agentstring
The user agent string identifying the client software making the request.
Authorizationstring·required
Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.
Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required
Path Parameters
Versionstring·required
The API version to use
Phone-Number-IDstring·required
The ID of the phone number registered with your WhatsApp Business Account
Query Parameters
user_wa_idstring·required
The WhatsApp ID of the user you want to check call permissions for
Responses
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.
Permission Status:
granted: You have active permission to call this user - pending: A permission request has been sent but not yet approved - denied: The user has denied call permissions - expired: Previous permission has expired
Available Actions:
start_call: Initiate a new call to this user - send_call_permission_request: Send a permission request to this user
Error Handling:
This endpoint may return various error codes including rate limiting errors if too many permission checks are made within a short period.
200
Call Permissions Check Success
Content Type: application/json
Schema: CallPermissionCheckResponsePayload
Show child attributes
CallPermissionCheckResponsePayload
messaging_productstring·required
Messaging product
permissionobject·required
Call permission details
Show child attributes
statusOne of "granted", "pending", "denied", "expired"·required
Current permission status for calling this user
expiration_timeinteger (int64)
Unix timestamp when the permission expires (if applicable)
actionsarray of object
Available actions and their restrictions
Show child attributes
actions[]object
Show child attributes
action_nameOne of "start_call", "send_call_permission_request"·required
Name of the action
can_perform_actionboolean·required
Whether the business can perform this action
limitsarray of object
Rate limits for this action
Show child attributes
limits[]object
Show child attributes
time_periodstring·required
Time period for the limit
current_usageinteger·required
Current usage count
max_allowedinteger·required
Maximum allowed usage
limit_expiration_timeinteger (int64)
Unix timestamp when the limit resets
400
Bad Request - Invalid request parameters
Content Type: application/json
429
Too Many Requests - Rate limit exceeded
Content Type: application/json
403
Forbidden - Template not approved or insufficient permissions
Content Type: application/json
500
Internal Server Error - An unexpected error occurred
Content Type: application/json
Select language
Select status code

POST /{Version}/{Phone-Number-ID}/calls

Use this endpoint to initiate, accept, reject, or terminate WhatsApp calls.
For initiating or managing a call:
Send a POST request with the appropriate action (connect, pre_accept, accept, reject, terminate).
For terminating a call:
Send a POST request with action "terminate" and the call_id.
Note: Response with error code 138006 indicates a lack of a call request permission for this business number from the WhatsApp user.

Request Syntax

Try it
Select language
Select status code
Header Parameters
User-Agentstring
The user agent string identifying the client software making the request.
Authorizationstring·required
Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.
Content-TypeOne of "application/json", "application/x-www-form-urlencoded", "multipart/form-data"·required
Path Parameters
Versionstring·required
The API version to use
Phone-Number-IDstring·required
The ID of the phone number registered with your WhatsApp Business Account
Optional
Content Type: application/json
Schema: Must be one of: CallRequestPayload, CallTerminateRequestPayload
Show child attributes
Must be one of: CallRequestPayload, CallTerminateRequestPayload
CallRequestPayload
Show child attributes
messaging_productstring·required
Messaging product
tostring·required
The number being called (callee)
actionOne of "connect", "pre_accept", "accept", "reject", "terminate"·required
The action being taken on the given call ID
sessionobject
Contains the session description protocol (SDP) type and description language
Show child attributes
sdp_typeOne of "offer", "answer"·required
SDP type - "offer" for connect action, "answer" for accept action
sdpstring·required
The SDP info of the device on the other end of the call. The SDP must be compliant with RFC 8866
biz_opaque_callback_datastring
CallTerminateRequestPayload
Show child attributes
messaging_productstring·required
Messaging product
call_idstring·required
The WhatsApp call ID
action"terminate"·required
Action to terminate the call
Responses
Use this endpoint to initiate, accept, reject, or terminate WhatsApp calls.
For initiating or managing a call:
Send a POST request with the appropriate action (connect, pre_accept, accept, reject, terminate).
For terminating a call:
Send a POST request with action "terminate" and the call_id.
Note: Response with error code 138006 indicates a lack of a call request permission for this business number from the WhatsApp user.
200
Call Management Success
Content Type: application/json
Schema: Must be one of: CallResponsePayload, CallTerminateResponsePayload
Show child attributes
Must be one of: CallResponsePayload, CallTerminateResponsePayload
CallResponsePayload
Show child attributes
messaging_productstring
callsarray of object
Show child attributes
calls[]object
Show child attributes
idstring
CallTerminateResponsePayload
Show child attributes
successboolean
Select language
Select status code

Authentication

Scheme
Type
Location
bearerAuth
HTTP Bearer
Header: Authorization

Usage Examples

bearerAuth:
Include Authorization: Bearer your-token-here in request headers

Global Authentication Requirements

All endpoints require:
bearerAuth

No comments to display

Back to top