whatsapp.meta_business_agent.handover.updated

Use whatsapp.meta_business_agent.handover.updated to handle this event at your webhook endpoint.

Triggers

Occurs when a supported handover callback transfers control away from a Public REST API Agent. Does not confirm Inbox assignment. Subscribe to whatsapp.meta_business_agent.handover.updated when you configure your webhook endpoint. This event is limited to Agents onboarded through the Public REST API. It reports control transferred away from the Agent. It does not confirm Inbox assignment.

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.meta_business_agent.handover.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappMetaBusinessAgent": {
    "agentId": "<AGENT_ID>",
    "metaAgentId": "<META_AGENT_ID>",
    "phoneNumberId": "<PHONE_NUMBER_ID>",
    "wabaId": "<WABA_ID>",
    "consumerPhoneNumber": "<CONSUMER_PHONE_NUMBER>",
    "controlState": "<CONTROL_STATE>",
    "actor": "<ACTOR>",
    "reason": "<REASON>",
    "timestamp": "<TIMESTAMP_VALUE>"
  }
}

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.meta_business_agent.handover.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
`whatsappMetaBusinessAgent`	object	Yes	Event-specific `whatsappMetaBusinessAgent` 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.

whatsappMetaBusinessAgent

Parameter	Type	Required	Description
`agentId`	string	No	YCloud Agent ID. Not a Meta Agent ID or an Inbox assignee ID.
`metaAgentId`	string	No	Meta Agent ID, when available.
`phoneNumberId`	string	No	Meta business phone number ID. Not an E.164 phone number.
`wabaId`	string	No	WhatsApp Business Account ID from the source callback, when available.
`consumerPhoneNumber`	string	No	Consumer phone number from the handover callback, normalized to E.164 when available. This is not the business number or phoneNumberId. Pattern: `^+[1-9][0-9]{7,14}$`.
`controlState`	string	No	Present for handover events. Currently APP_CONTROL_TAKEN for Public REST API handover callbacks. Does not confirm an Inbox assignment or message delivery.
`actor`	string	No	Optional handover source actor. For a control_passed handoff this is the previous owner app ID, not the employee who receives the conversation.
`reason`	string	No	Optional provider handover reason or metadata, for example customer_request. Not a closed enum.
`timestamp`	integer (int64)	No	Source event time in Unix milliseconds, or processing time if unavailable.

Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative. APP_CONTROL_TAKEN reports control transfer, not an Inbox employee assignment or custom handoff message delivery. actor is the previous owner app ID in this example.

{
  "id": "evt_example_agent_handover",
  "type": "whatsapp.meta_business_agent.handover.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:04.000Z",
  "whatsappMetaBusinessAgent": {
    "agentId": "00000000-0000-4000-8000-000000000001",
    "metaAgentId": "META_AGENT_ID",
    "phoneNumberId": "PHONE_NUMBER_ID",
    "wabaId": "WABA_ID",
    "consumerPhoneNumber": "+12025550124",
    "controlState": "APP_CONTROL_TAKEN",
    "actor": "PREVIOUS_OWNER_APP_ID",
    "reason": "customer_request",
    "timestamp": 1788919204000
  }
}

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.meta_business_agent.handover.updated

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappMetaBusinessAgent

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​whatsappMetaBusinessAgent

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappMetaBusinessAgent

Example