什么是控制权移交事件
订阅 whatsapp.meta_business_agent.handover.updated。
当 YCloud 为通过 API 创建的 Agent 处理支持的移交/控制回调时，您会收到此事件。它仅报告控制权转移，而不代表收件箱分配的结果或自定义转接消息的发送状态。
与两个 Echo 事件不同，此事件有意保留了 whatsappMetaBusinessAgent 对象，因为 Agent 和控制元数据是移交协议的一部分。
开始之前
- 通过 公共 REST API 接入 Agent。
- 在同一账户中为活跃的 Webhook 端点订阅
whatsapp.meta_business_agent.handover.updated。
- 对照原始请求体验证
YCloud-Signature，持久接收每个事件并以幂等方式处理。
在控制台创建的 Agent 不会发送此客户 Webhook。其收件箱同步属于独立流程。
工作原理
所有示例均使用占位标识符。请根据外层 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 处于草稿状态期间处理的控制回调会被忽略。
负载不会凭空生成客户身份。当回调未提供有效电话号码时，consumerPhoneNumber 会被省略，也不会从相邻消息中推断 BSUID。phoneNumberId 标识商业号码，该号码可以服务多个客户。
POST 请求中包含这些 JSON 格式的请求体。
在持久接收事件后返回 2xx 响应。耗时任务请以异步方式处理。
Agent 将控制权移交给您的应用程序
APP_CONTROL_TAKEN 报告控制权转移，不代表收件箱员工分配或自定义转接消息送达。在此示例中，actor 是前一个持有控制权的应用 ID。
在存在 consumerPhoneNumber 时，使用它将控制权转换关联到对应客户。请勿根据此事件推断收件箱分配或消息送达情况。
相关示例
