> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Agent handover updated

> Observe supported Agent control handover callbacks and understand their correlation limits.

## 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](/en/api-reference/meta-business-agents/onboard).
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.

<Warning>
  Console-created Agents do not emit this customer webhook. Their Inbox synchronization is a separate flow.
</Warning>

See [Configure webhooks](/en/api-reference/guides/api-fundamentals/configure-webhooks#subscribe-to-echo-and-handover-events) 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.

<Warning>
  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.
</Warning>

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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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
  }
}
```

### Response

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 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.

### Related examples

* [WhatsApp echo message created](/en/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-created)
* [WhatsApp echo message updated](/en/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-updated)
* [Echo and Agent handover examples](/en/api-reference/guides/examples/webhook-examples/overview#echo-and-agent-handover-events)
* [Complete payload catalog](/en/api-reference/guides/examples/webhook-examples/webhook-payload-examples)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.