whatsapp.call.status.updated

Use whatsapp.call.status.updated to handle this event at your webhook endpoint.

Triggers

Occurs when a WhatsApp call status is updated. Subscribe to whatsapp.call.status.updated when you configure your webhook endpoint.

Syntax

YCloud sends an HTTP POST request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under Parameters. Optional fields and other variants are described below.

{
  "id": "<ID>",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "callingStatusUpdated": {
    "wabaId": "<WABA_ID>",
    "wacid": "<WACID>",
    "phoneId": "<PHONE_ID>",
    "status": "<STATUS>",
    "recipientPhone": "<RECIPIENT_PHONE>"
  }
}

Parameters

Validate the YCloud-Signature HTTP header before you process the JSON body. See signature validation.

Event envelope

Parameter	Type	Required	Description
`id`	string	Yes	Unique ID for the event. Minimum length: `6`. Maximum length: `128`.
`type`	string	Yes	Always `whatsapp.call.status.updated`.
`apiVersion`	string	Yes	The API version used to render this event.
`createTime`	string (date-time)	Yes	The time at which this event was created, formatted in RFC 3339. e.g., `2022-06-01T12:00:00.000Z`.

Event payload

Parameter	Type	Required	Description
`callingStatusUpdated`	object	No	Event-specific `callingStatusUpdated` payload.

The four common envelope fields are required. Payload fields depend on the event variant. In each object table, Required applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required.

callingStatusUpdated

Parameter	Type	Required	Description
`id`	string	No	Unique ID for the call event (optional field, may not be present).
`wabaId`	string	No	WhatsApp Business Account ID.
`wacid`	string	Yes	The WhatsApp call ID. This ID uniquely identifies the call session.
`phoneId`	string	No	The WhatsApp Business phone number ID (optional field, may not be present).
`status`	string	Yes	The current status of the call. `RINGING`: Business initiated call is ringing the user. `ACCEPTED`: Business initiated call is accepted by the user. `REJECTED`: Business initiated call is rejected by the user.
`recipientPhone`	string	No	The recipient’s phone number in E.164 format.
`recipientUserId`	string	No	The recipient’s WhatsApp Business-scoped user ID (BSUID).
`parentRecipientUserId`	string	No	The recipient’s parent WhatsApp Business-scoped user ID.
`customerProfile`	object	No	The customer’s profile information, including WhatsApp username when available.

callingStatusUpdated.customerProfile

Parameter	Type	Required	Description
`name`	string	No	Name of the WhatsApp account.
`username`	string	No	WhatsApp username.

Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative.

WhatsApp call status updated event

Example payload when a WhatsApp call status is updated

{
  "id": "evt_676e5ab57a9cb742d02d7646",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:28.422Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "status": "RINGING",
    "recipientPhone": "+6281361905133"
  }
}

Business initiated call is ringing the user

{
  "id": "evt_676e5ab57a9cb742d02d7646",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:28.422Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "status": "RINGING",
    "recipientPhone": "+6281361905133",
    "recipientUserId": "ID.13491208655302741918",
    "parentRecipientUserId": "ID.11815799212886844830"
  }
}

Business initiated call is accepted by the user

{
  "id": "evt_67724ad42b4b206adc55f099",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:42:00.577Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "status": "ACCEPTED",
    "recipientPhone": "+6281361905133",
    "recipientUserId": "ID.13491208655302741918",
    "parentRecipientUserId": "ID.11815799212886844830"
  }
}

Business initiated call is rejected by the user

{
  "id": "evt_677258526a15af2a8c7184a3",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:32.093Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCAB",
    "status": "REJECTED",
    "recipientPhone": "+6281361905133",
    "recipientUserId": "ID.13491208655302741918",
    "parentRecipientUserId": "ID.11815799212886844830"
  }
}

After verifying the signature and durably accepting the event, return a 2xx response. Process slow work asynchronously.

HTTP/1.1 200 OK

For scenario walkthroughs, see annotated examples.

Getting Started

Guides

Endpoints

Webhook reference

whatsapp.call.status.updated

Triggers

Syntax

Parameters

Event envelope

Event payload

callingStatusUpdated

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​callingStatusUpdated

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

callingStatusUpdated

Example