Skip to main content

​
What it is

Subscribe to whatsapp.meta_business_agent.handover.updated. You receive this event when YCloud processes a supported handover/control callback for an API-created Agent. It reports control transfer, not the outcome of an Inbox assignment or a custom handoff message. Unlike the two Echo events, this event intentionally keeps the whatsappMetaBusinessAgent object because Agent and control metadata are part of the handover contract.

​
Before you begin

  1. Onboard the Agent through the Public REST API.
  2. Subscribe an active webhook endpoint in the same account to whatsapp.meta_business_agent.handover.updated.
  3. Verify YCloud-Signature against the raw request body, durably accept each event, and process it idempotently.
Console-created Agents do not emit this customer webhook. Their Inbox synchronization is a separate flow.
See Configure webhooks for endpoint setup.

​
How it works

All examples use placeholder identifiers. Route by the outer type and read whatsappMetaBusinessAgent, not whatsappMessage, whatsappEchoMessage, or data. Deduplicate repeated deliveries with the outer id. The nested timestamp is an integer in Unix milliseconds; createTime is an RFC 3339 string.
  • controlState is currently APP_CONTROL_TAKEN for supported API Agent handover callbacks.
  • consumerPhoneNumber comes from the handover callback’s sender.phone_number and is normalized to E.164 when valid. It is not the business number or phoneNumberId.
  • The current handover contract does not expose recipientUserId or parentRecipientUserId. Missing consumer identity is not recovered from a neighboring message callback.
  • For the control_passed example below, actor identifies the previous owner app, not the receiving employee.
  • reason is optional provider metadata. Treat it as an open string, not a fixed enum.
  • This is not a notification for every take, release, Set Live, or Set Draft request. Control callbacks processed while the Agent is Draft are ignored.
The payload does not invent a consumer identity. consumerPhoneNumber is omitted when the callback does not provide a valid phone number, and no BSUID is inferred from adjacent messages. phoneNumberId identifies the business number, which can serve many customers.
Do not treat this event as proof that an employee was assigned or a custom handoff message was sent or delivered.

​
Request

YCloud sends these JSON bodies in HTTP POST requests to your configured webhook URL.

​
Response

Return a 2xx response after durably accepting the event. Process slow work asynchronously.

​
Agent hands control to your application

​
Request

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.

​
Response

​
Explanation

Use consumerPhoneNumber to correlate the control transition to the consumer when it is present. Do not infer an Inbox assignment or message delivery from this event.