Skip to main content

概述

订阅 whatsapp.meta_business_agent.handover.updated。 当 YCloud 处理通过 API 创建的 Meta Business Agent 的受支持移交/控制权回调时,您会收到此事件。它报告的是控制权转移,而不是收件箱分配的结果或自定义移交消息的结果。 与两个 Echo 事件不同,此事件有意保留了 whatsappMetaBusinessAgent 对象,因为 Agent 和控制权元数据属于移交协议的一部分。

准备工作

  1. 通过 Public REST API 接入 Agent。
  2. 为同一账户中处于活动状态的 Webhook 终端节点订阅 whatsapp.meta_business_agent.handover.updated。
  3. 根据原始请求体验证 YCloud-Signature,持久接收每个事件,并对其进行幂等处理。
通过控制台创建的 Agent 不会发出此客户 Webhook。它们的收件箱同步属于单独的流程。
有关终端节点设置,请参阅配置 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 标识商业号码,该号码可以为多个客户提供服务。
不要将此事件视为已分配员工或已发送/送达自定义移交消息的证明。

请求

YCloud 会在发送给您所配置 Webhook URL 的 HTTP POST 请求中附带这些 JSON 请求体。

响应

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

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

请求

APP_CONTROL_TAKEN 报告的是控制权转移,而不是收件箱员工分配或自定义移交消息的送达。在此示例中,actor 是前一个所有者应用 ID。

响应

说明

在存在 consumerPhoneNumber 时,使用它将控制权过渡与客户关联起来。不要根据此事件推断收件箱分配或消息送达情况。

相关示例