> ## 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 控制权移交已更新

> 观察支持的 Agent 控制权移交回调并了解其关联限制。

## 什么是控制权移交事件

订阅 `whatsapp.meta_business_agent.handover.updated`。

当 YCloud 为通过 API 创建的 Agent 处理支持的移交/控制回调时，您会收到此事件。它仅报告控制权转移，而不代表收件箱分配的结果或自定义转接消息的发送状态。

与两个 Echo 事件不同，此事件有意保留了 `whatsappMetaBusinessAgent` 对象，因为 Agent 和控制元数据是移交协议的一部分。

## 开始之前

1. 通过 [公共 REST API](/zh/api-reference/meta-business-agents/onboard) 接入 Agent。
2. 在同一账户中为活跃的 Webhook 端点订阅 `whatsapp.meta_business_agent.handover.updated`。
3. 对照原始请求体验证 `YCloud-Signature`，持久接收每个事件并以幂等方式处理。

<Warning>
  在控制台创建的 Agent 不会发送此客户 Webhook。其收件箱同步属于独立流程。
</Warning>

有关端点配置，请参见[配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks#subscribe-to-echo-and-handover-events)。

## 工作原理

所有示例均使用占位标识符。请根据外层 `type` 进行路由，并读取 `whatsappMetaBusinessAgent`，而不是 `whatsappMessage`、`whatsappEchoMessage` 或 `data`。

使用外层 `id` 对重复推送进行去重。嵌套的 `timestamp` 为 Unix 毫秒整数；`createTime` 为 RFC 3339 格式字符串。

* 对于支持的 API Agent 移交回调，`controlState` 当前为 `APP_CONTROL_TAKEN`。
* `consumerPhoneNumber` 来自移交回调的 `sender.phone_number`，有效时会规范化为 E.164 格式。它不是商业号码，也不是 `phoneNumberId`。
* 当前的移交协议不暴露 `recipientUserId` 或 `parentRecipientUserId`。缺失的客户身份不会从相邻的消息回调中恢复。
* 在下面的 `control_passed` 示例中，`actor` 标识前一个持有控制权的应用，而不是接收该对话的员工。
* `reason` 是可选的提供商元数据。应将其视为开放字符串，而非固定枚举。
* 这并不是针对每个 `take`、`release`、发布（Set Live）或设为草稿（Set Draft）请求的通知。在 Agent 处于草稿状态期间处理的控制回调会被忽略。

<Warning>
  负载不会凭空生成客户身份。当回调未提供有效电话号码时，`consumerPhoneNumber` 会被省略，也不会从相邻消息中推断 BSUID。`phoneNumberId` 标识商业号码，该号码可以服务多个客户。
</Warning>

请勿将此事件视为员工已被分配或自定义转接消息已发送/送达的证明。

## 请求

YCloud 会在发送给您配置的 Webhook URL 的 HTTP `POST` 请求中包含这些 JSON 格式的请求体。

## 响应

在持久接收事件后返回 `2xx` 响应。耗时任务请以异步方式处理。

## Agent 将控制权移交给您的应用程序

### 请求

APP\_CONTROL\_TAKEN 报告控制权转移，不代表收件箱员工分配或自定义转接消息送达。在此示例中，actor 是前一个持有控制权的应用 ID。

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

### 响应

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

### 说明

在存在 `consumerPhoneNumber` 时，使用它将控制权转换关联到对应客户。请勿根据此事件推断收件箱分配或消息送达情况。

### 相关示例

* [WhatsApp 回显消息已创建](/zh/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-created)
* [WhatsApp 回显消息已更新](/zh/api-reference/guides/examples/webhook-examples/whatsapp-echo-message-updated)
* [Echo 与 Agent 移交示例](/zh/api-reference/guides/examples/webhook-examples/overview#echo-and-agent-handover-events)
* [完整 Payload 目录](/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)


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