\{
"messaging_product": "whatsapp",
"permission": {
"status": "temporary",
"expiration_time": 1745343479
},
"actions": [\
{\
"action_name": "send_call_permission_request",\
"can_perform_action": true,\
"limits": [\
{\
"time_period": "PT24H",\
"max_allowed": 1,\
"current_usage": 0,\
},\
{\
"time_period": "P7D",\
"max_allowed": 2,\
"current_usage": 1,\
}\
]\
},\
{\
"action_name": "start_call",\
"can_perform_action": false,\
"limits": [\
{\
"time_period": "PT24H",\
"max_allowed": 5,\
"current_usage": 5,\
"limit_expiration_time": 1745622600,\
}\
]\
}\
}\
}\
```\
\
#### Response parameters\
\
| Parameter | Description |\
| --- | --- |\
| `permission`<br />_JSON Object_ | The permission object contains two values:<br />`status` _(String)_ — The current status of the permission.<br />Can be either:<br />`“no_permission”`<br />`"temporary"`<br />`“permanent”`<br />`expiration` _(Integer)_ — The Unix time at which the permission will expire in UTC timezone.<br />If the permission is permanent, this field won’t be present. |\
| `actions`<br />_JSON Object_ | A list of actions a business phone number may undertake to facilitate a call permission or a business initiated call.<br />Current actions are:<br />`send_call_permission_request`: Represents the action of sending new call permissions request messages to the WhatsApp user.<br />`start_call`: Represents the action of establishing a new call with the WhatsApp user. Establishing a new call means that the call was successfully picked up by the consumer.<br />For example, `send_call_permission_request` having a `can_perform_action` of `true` means that your business can send a call permission request to the WhatsApp user in question<br />`can_perform_action` ( _Boolean_) —<br />A flag indicating whether the action can be performed now, taking into account all limits. |\
| `limits`<br />_JSON Object_ | A list of time-bound restrictions for the given `action_name`.<br />Each `action_name` has 1 or more restrictions depending on the timeframe.<br />For example, a business can only send 2 permission requests in a 24-hour period.<br />`limits` contains the following fields:<br />`time_period` ( _String_) — The span of time in which the limit applies, represented in the ISO 8601 format.<br />`max_allowed` ( _Integer_) — The maximum number of actions allowed within the specified time period.<br />`current_usage` ( _Integer_) — The current number of actions the business has taken within the specified time period.<br />`limit_expiration_time` ( _Integer_) — The Unix time at which the limit will expire in UTC timezone.<br />If `current_usage` is under the max allowed for the limit, this field won’t be present. |\
\
#### Error response\
\
Possible errors that can occur:\
\
Invalid `phone-number-id`\
If the consumer phone number is uncallable, the api response will be `no_permission`.\
Permissions/Authorization errors.\
Rate limit reached. A maximum of 5 requests in a 1 second window can be made to the API.\
Calling is not enabled for the business phone number.\
\
[View Calling API Error Codes and Troubleshooting for more information](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/troubleshooting)\
\
[View general Cloud API Error Codes here](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)\
\
## User calling permission request webhook\
\
This webhook is sent back after requesting user calling permissions.\
\
The webhook changes depending on if the user:\
\
accepts or rejects the request\
gives permission by responding to a request or by calling the business\
\
Lastly, the user can grant permanent calling permission to the business, which is represented in the `is_permanent` parameter.\
\
#### Webhook sample\
\
```\
{\
. . .\
\
"messages": [{\
"from": "{customer_phone_number}",\
"id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",\
"timestamp": "{timestamp}",\
"context": {\
"from": "{customer_phone_number}",\
"id": "wacid.gBGGFlaCmZ9plHrf2Mh-o"\
},\
"interactive": {\
"type": "call_permission_reply",\
"call_permission_reply": {\
"response":"accept",\
"is_permanent":false,\
"expiration_timestamp": "{timestamp}",\
"response_source": "[user_action|automatic]"\
}\
}\
],\
. . .\
}\
```\
\
#### Webhook values\
\
| Placeholder | Description |\
| --- | --- |\
| `customer_phone_number`<br />_String_ | The phone number of the customer |\
| `context.id`<br />_String_ | Can be either of two values<br />Message ID of the permission request message sent by the business to the customer number. Shows when a permission decision is made by the user in response to a call permission request.<br />Call ID of the missed call placed by the business to the customer number. Shows when callback permission is enabled in settings and the user calls the business. |\
| `response`<br />_String_ | The WhatsApp users response to the call permission request message<br />Can be `accept` or `reject` |\
| `is_permanent`<br />_Boolean_ | Indicates if the permission is permanent or not. For temporary permission this will always be false. |\
| `expiration_timestamp`<br />_Integer_ | Time in seconds when this call permission expires if the WhatsApp user approved it |\
| `response_source`<br />_String_ | The source of this permission<br />Possible values for accepted call permissions are:<br />`user_action`: User approved or rejected the permission<br />`automatic`: An automatic permission approval due to the WhatsApp user initiating the call |\
\
Did you find this page helpful?\
\
\
\
\
\
ON THIS PAGE\
\
Overview\
\
Limits (Per business + WhatsApp user pair)\
\
Call permission request basics\
\
Free form vs template call permission request message\
\
Client Application UI Experience\
\
Call permission request flow and sample messages\
\
Allow calls\
\
Temporarily allow calls\
\
Template message\
\
Free form message types\
\
Updating call permission on business profile\
\
Consecutive unanswered calls\
\
Call permission request expiration scenarios\
\
Send free form call permission request message\
\
Request syntax\
\
Request body\
\
Body parameters\
\
Success response\
\
Error response\
\
Create and send call permission request template messages\
\
Create message template\
\
Request syntax\
\
Request body\
\
Body parameters\
\
Template status response\
\
Error response\
\
Send message template\
\
Request syntax\
\
Request body\
\
Get current call permission state\
\
Request syntax\
\
Request parameters\
\
Response body\
\
Response parameters\
\
Error response\
\
User calling permission request webhook\
\
Webhook sample\
\
Webhook values\
\
* * *
With body only
With no text body
Permission request expires after 7 days — User does not interact
Previous permission request expires immediately — User does not interact / New call permission request is received
Previous permission request expires immediately — User allows / Interacts with the new request
