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

> Occurs when a supported handover callback transfers control away from a Public REST API Agent. Does not confirm Inbox assignment.

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](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

### 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](https://datatracker.ietf.org/doc/html/rfc3339). 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.

```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
  }
}
```

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

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

For scenario walkthroughs, see [annotated examples](https://docs.ycloud.com/en/api-reference/guides/examples/webhook-examples/whatsapp-meta-business-agent-handover-updated).


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