Messenger Platform
Check and obtain call permissions
Updated: Apr 6, 2026
Before placing a call to a consumer, you must verify that the consumer has granted call permission. Use the call permissions check API to query the current status, and send a permission request if needed.
Before you begin
- Complete the setup described in the Calling overview
- Subscribe to the
call_permission_replywebhook field
Check call permission status
Use this API to check a consumer’s real-time call permission status and decide whether to request permission or start a call directly.
Request syntax
GET /{page-id}/messenger_call_permissions?psid={psid}
Request parameters
| Property | Description |
|---|---|
page-id string | The delegate ID of the business Facebook Page |
psid string | Unique PSID for the consumer on this Page |
Example response
{ "permission": { "status": "has_permission", "expiration_time": 1745343479 }, "actions": [ { "action_name": "send_call_permission_request", "can_perform": false, "limits": [ { "time_period": "PT24H", "max_allowed": 2, "current_usage": 1 } ] }, { "action_name": "start_call", "can_perform": true } ] }
Response fields
| Property | Description |
|---|---|
permission JSON | The current permission status:
expiration_time (included only when status is has_permission): Unix timestamp (in seconds, UTC) when the permission expires. Default expiration is 7 days after the consumer grants permission. |
actions JSON | List of actions you can take:
Each action includes can_perform (boolean) and optional limits with time_period, max_allowed, and current_usage. |
Error response
The following errors can occur:
- Invalid Page ID or PSID
- Permissions or authorization errors
- Not allowed for business-initiated calling
- Audio calling is not enabled
For more details, see the Messenger Platform error codes reference.
Send a call permission request
To place a call to a consumer, you must first receive their permission. You can obtain permission in the following ways:
- Send a call permission request that the consumer approves
- The consumer provides implicit callback permission after:
- A fully connected call with the business
- The consumer calls the business but the business does not pick up
Each calling permission expires after 7 days. You can send at most 2 call permission requests per thread per day.
Request syntax
POST /{page-id}/messages { "recipient": { "id": "{psid}" }, "message": { "attachment" : { "type":"template", "payload":{ "template_type":"calling_optin" } } } }
Request parameters
| Property | Description |
|---|---|
recipient string | The Page-scoped ID of the consumer to whom the opt-in is requested |
template_type string | Must be calling_optin |
The consumer receives a message with Accept and Decline buttons.
Example response
{ "recipient": { "id": "{psid}" }, "message_id": "{mid}" }
Error response
The following errors can occur:
- Send API errors such as insufficient permission or messaging outside of 24-hour window
- Rate limit reached (2 permission requests per thread per day)
For more details, see the Messenger Platform error codes reference.
Call permission reply webhook
When the consumer clicks Accept or Decline, you receive a postback webhook with the
call_permission_reply field.{ "object": "page", "entry": [ { "sender": { "id": "{psid}" }, "recipient": { "id": "{page-id}" }, "timestamp": 1671644824, "call_permission_reply": { "response": "[approve|reject]", "expiration_timestamp": "{timestamp}" } } ] }
| Property | Description |
|---|---|
response string | The consumer’s response: approve or reject |
expiration_timestamp Unix timestamp | When the permission expires. Only included if the consumer approved the request. |
Next steps
Once the consumer has granted permission, initiate a call.
Did you find this page helpful?
