Calling webhooks

Updated: Mar 23, 2026

When a call is initiated or received, Meta sends webhook events on the calls field to notify you of call lifecycle changes. The webhook structure follows the same pattern as Messenger Platform webhooks.

Subscribe to the calls webhook field to receive these events. For business-initiated calls, also subscribe to the call_permission_reply field.

Connect

Applies to: consumer-initiated and business-initiated calls

This webhook notifies you in near real-time when a call is initiated. For consumer-initiated calls, respond by calling /{page-id}/calls with action=accept to establish the WebRTC connection.

{
  "object": "page",
  "entry": [
    {
      "id": "{page-id}",
      "time": 1671644824,
      "calls": [
        {
          "id": "c_M5YPhGE5jm0L_PMQdScLlYJlR7tU_f0rgXiTQ",
          "to": "106378625516323",
          "from": "5275811702471834",
          "event": "connect",
          "timestamp": 1671644824,
          "call_direction": "[business_initiated|user_initiated]"
        }
      ]
    }
  ]
}

Property	Description
`id` string	Unique ID for the call. Use this in your accept, reject, or terminate API calls.
`to` string	Callee of the call (Page ID)
`from` string	Caller of the call (PSID)
`event` string	`connect` or `terminate`
`timestamp` Unix timestamp	Start time of the call from the caller’s perspective
`call_direction` string	`business_initiated` or `user_initiated`

Call status

Applies to: business-initiated calls only

This webhook notifies you when a business-initiated call begins ringing or is accepted by the consumer.

{
  "object": "page",
  "entry": [
    {
      "id": "{page-id}",
      "time": 1671644824,
      "calls": [
        {
          "id": "c_M5YPhGE5jm0L_PMQdScLlYJlR7tU_f0rgXiTQ",
          "event": "call_status",
          "timestamp": 1671644824,
          "recipient_id": "{psid}",
          "call_status": "[ringing | accepted]"
        }
      ]
    }
  ]
}

Property	Description
`id` string	Unique ID for the call
`event` string	`call_status`
`recipient_id` string	PSID of the consumer
`call_status` string	`ringing`: The outgoing call is ringing the consumer’s device `accepted`: The consumer accepted the call

Media update

Applies to: business-initiated calls only

This webhook notifies you when a consumer-side media event occurs, providing new SDP information that you must apply to your local peer connection. Triggers include:

Consumer picks up the business-initiated call

Consumer mutes or unmutes

When you receive this webhook, generate an SDP answer from the offer and apply it to your local peer connection to establish or update the WebRTC connection.

{
  "object": "page",
  "entry": [
    {
      "id": "{page-id}",
      "time": 1671644824,
      "calls": [
        {
          "id": "c_M5YPhGE5jm0L_PMQdScLlYJlR7tU_f0rgXiTQ",
          "event": "media_update",
          "timestamp": 1671644824,
          "session": {
              "version": 1,
              "sdp_renegotiation": {
                  "sdp_type": "offer",
                  "sdp": "<<RFC 4566 SDP>>"
              }
          }
        }
      ]
    }
  ]
}

Property	Description
`event` string	`media_update`
`session.version` integer	Incremented each time Meta provides new SDP. If you receive multiple `media_update` webhooks, apply the one with the highest version number.
`session.sdp_renegotiation` JSON	Contains the SDP offer from Meta. Generate an answer from this offer and apply it to your local peer connection. `sdp`: SDP data compliant with RFC 4566⁠ `sdp_type`: `offer`

Terminate

Applies to: consumer-initiated and business-initiated calls

This webhook notifies you when the call ends for any reason. This occurs when:

The consumer hangs up

Your app calls /{page-id}/calls with action=terminate

Your app calls /{page-id}/calls with action=reject (consumer-initiated calls only)

{
  "object": "page",
  "entry": [
    {
      "id": "{page-id}",
      "time": 1671644824,
      "calls": [
        {
          "id": "c_M5YPhGE5jm0L_PMQdScLlYJlR7tU_f0rgXiTQ",
          "event": "terminate",
          "timestamp": 1671644824,
          "status" : "[Failed | Completed]",
          "start_time" : 1671644824,
          "end_time" : 1671644944,
          "duration" : 120
        }
      ]
    }
  ]
}

Property	Description
`status` string	Final status of the call: `Completed`: Call finished normally (includes calls rejected by the consumer or business) `Failed`: Call failed mid-connection
`start_time` Unix timestamp	When the call started
`end_time` Unix timestamp	When the call ended
`duration` integer	Call duration in seconds, counted from when the business connects. Empty if the business did not successfully connect.

Did you find this page helpful?