Check and obtain call permissions

Updated: Apr 6, 2026

Copy for LLM

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_reply webhook 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: `no_permission`: No permission found for this consumer `has_permission`: Consumer granted a permanent permission `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: `send_call_permission_request`: Send a new call permission request to the consumer `start_call`: Establish a new call with the consumer (requires existing permission and connected call quota within limits) 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.

Call permission request 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.