Meta Business Agent 控制权移交

​

功能说明

​

准备工作

1. 通过 Public REST API 接入 Agent。
2. 将同一账户中的活动 Webhook 端点订阅到 whatsapp.meta_business_agent.handover.updated。
3. 根据原始请求体验证 YCloud-Signature，持久化接收每个事件，并进行幂等处理。

​

工作原理

• 对于受支持的 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 处于 Draft 状态时处理的控制权回调将被忽略。

​

请求

​

响应

​

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

​

请求

{
  "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/1.1 200 OK

​

说明

​

相关示例

• WhatsApp echo 消息已创建
• WhatsApp echo 消息已更新
• Echo 与 Agent 移交示例
• 完整 Payload 目录