Initiate and end a call

Updated: Mar 23, 2026

After the consumer has granted call permission, use the new call API to initiate a call by providing an SDP offer.

Before you begin

Complete the setup described in the Calling overview

Verify the consumer has granted call permission

Initiate a call

Use this API to start a call by providing the consumer’s PSID and an SDP offer. A successful response includes an SDP answer that you apply to your local peer connection.

Request syntax

POST /{page-id}/calls
{
  "platform": "messenger",
  "to": "{psid}",
  "action": "connect",
  "session": {
      "sdp_type": "offer",
      "sdp": "<<RFC 4566 SDP>>"
   }
}

Request parameters

Property	Description
`to` string	The Page-scoped ID of the consumer to call
`action` string	Set to `connect` to initiate a call
`session` JSON	Connection information containing: `sdp`: SDP offer compliant with RFC 4566⁠ `sdp_type`: Set to `offer`

Example response

{
  "success": true,
  "id": "c_M5YPhGE5jm0L_PMQdScLlYJlR7tU_f0rgXinCqnTQ",
  "session": {
    "sdp_response": {
      "sdp_type": "answer",
      "sdp": "<<RFC 4566 SDP>>"
    }
  }
}

Response fields

Property	Description
`success` boolean	Whether the operation was successful
`id` string	Unique ID for this call. Use this ID for subsequent API calls and to correlate webhooks.
`session` JSON	Contains `sdp_response` with the SDP answer. Apply this answer to your local peer connection.

Error response

The following errors can occur:

Invalid Page ID

Permissions or authorization errors

Consumer has not given permission to call

Request format validation errors (for example, connection info, SDP, or ICE)

For more details, see the Messenger Platform error codes reference.

Terminate a call

Use this API to end an active call.

Request syntax

POST /{page-id}/calls
{
  "platform": "messenger",
  "call_id": "{call-id}",
  "action" : "terminate"
}

Request parameters

Property	Description
`platform` Optional string	Only `Messenger` is supported
`call_id` string	ID of the call from the webhook or the new call API response
`action` string	Set to `terminate`

Example response

{
  "success" : true
}

Error response

The following errors can occur:

Invalid call ID or Page ID

Call already terminated

Cannot terminate a failed or completed call

Permissions or authorization errors

For more details, see the Messenger Platform error codes reference.

Next steps

Handle calling webhooks for call status, media updates, and termination events

See the end-to-end call flow for a complete walkthrough www/flib/intern/public-developer-docs/social/mdsourcedc/business-messaging/messenger-platform/_staging/calling/biz2consumer/webhooks.md