基本概念
Webhook 是 YCloud 在消息发送状态、入站消息、联系人、模板、通话以及其他资源发生变化时,向您的应用程序发送的 HTTPS 请求。开始之前
- 将您的 YCloud API 密钥存储在
YCLOUD_API_KEY中。 - 部署一个可公开访问的 HTTPS 端点。
- 保留原始请求体以进行签名验证。
- 确定您的应用程序需要哪些事件类型。
运作方式
- 创建 Webhook 端点并订阅事件类型。
- 保存返回的端点
secret。 - YCloud 向您的端点发送事件请求。
- 在信任请求之前先验证
YCloud-Signature。 - 及时返回
2xx响应。 - 以幂等方式处理事件,因为推送可能会重复发生。
请求
使用POST /webhookEndpoints 创建端点。
请求字段
请求示例
订阅回显与移交事件
对于通过公共 REST API 入驻的 Agent,请使用以下订阅创建端点。控制台创建的 Agent 不会发出这三个事件。如需修改现有端点,请保留您仍需要的任何事件订阅。whatsappMessage 负载。移交事件携带 whatsappMetaBusinessAgent 并保留其 Agent/控制信息。它们不使用 WhatsApp Business App whatsapp.smb.message.echoes 协议。请参阅 回显与移交事件详情 以获取字段定义、示例、顺序以及移交关联限制。
订阅 Messenger 消息事件
创建或更新端点时,请在
enabledEvents 中包含您需要的事件名称。例如,订阅所有四种事件:
messengerInboundMessage.id 和 metaMessageId,替换 text.body,并添加 editCount 和 editTime。消息的 sendTime 和 createTime 保持不变;事件外层 envelope 的 createTime 为编辑时间。未编辑的消息会省略编辑字段。仅更新现有的入站消息。较旧的编辑会被忽略;不会重建缺失的消息和历史编辑。请按消息 ID 关联更新,并使用累计计数以避免将较旧的文本应用覆盖较新的版本。源端重试可能会为同一条已保存的编辑生成另一个事件 ID。请参阅入站编辑示例。
回应事件包含 pageId、作出回应的客户的 psid、目标 metaMessageId 以及 action(react 或 unreact)。可选的 reaction 和 emoji 可能会缺失,特别是对于 unreact。回应不会改变消息的发送状态。目标消息可能来源于 YCloud API 之外,因此该事件不要求具备本地消息记录,也不包含本地消息 ID。
事件的 createTime 保留了源端互动时间。客户送达重试会保留其事件 id 和负载。对于重复的互动,源端回调处理可能会生成另一个事件 ID;请勿将事件 ID 视作回应或消息的唯一标识。有关这两种操作,请参阅回应负载示例。
响应
响应会返回已创建的端点及其签名secret。请妥善安全地存储该密钥。YCloud 会使用它来生成 Webhook 签名。
响应示例
响应字段
接收事件
事件请求
YCloud 会向配置的url 发送一个 JSON 事件对象。该事件包含诸如 id、type、apiVersion 和 createTime 等通用字段,以及特定类型的载荷。
您的处理程序应当:
- 读取原始请求体。
- 在信任载荷之前,先使用端点密钥验证
YCloud-Signature请求头。 - 及时返回成功的
2xx响应。 - 将耗时的处理任务移至队列。
- 对事件处理实现幂等设计,以确保重复投递不会导致重复执行业务操作。
接收端响应
在签名和请求被接受后,立即返回成功的2xx HTTP 响应。响应体可以为空。
2xx 响应可能会导致 YCloud 重试发送事件,因此请按事件 id 进行去重。
常见载荷示例
展开事件以查看其完整的载荷示例。这些示例来自 OpenAPI Webhook 规范。如需查看所有受支持的事件类型,请参阅所有 Webhook 载荷示例。联系人创建事件
联系人创建事件
创建新联系人时的载荷示例
联系人删除事件
联系人删除事件
删除联系人时的载荷示例
客户取消订阅事件
客户取消订阅事件
客户取消订阅时的载荷示例
客户恢复订阅
客户恢复订阅
客户恢复订阅时的载荷示例
WhatsApp 模板归档事件
WhatsApp 模板归档事件
WhatsApp 模板归档时的载荷示例
WhatsApp 模板取消归档事件
WhatsApp 模板取消归档事件
WhatsApp 模板取消归档时的载荷示例。模板状态为 Meta 返回的当前状态,并不代表重新进行了审核。
WhatsApp 通话接通事件
WhatsApp 通话接通事件
WhatsApp 通话接通时的载荷示例
WhatsApp 通话结束事件
WhatsApp 通话结束事件
WhatsApp 通话结束时的载荷示例
WhatsApp 通话状态更新事件
WhatsApp 通话状态更新事件
WhatsApp 通话状态更新时的载荷示例
轮换端点密钥
如果密钥泄露或出于安全策略考虑,请轮换密钥:屡次接收通知失败的端点可能会变为
pending 状态并停止接收事件。请监控 Webhook 失败情况及端点状态。
