如需查看基于 Schema 生成的完整目录,请参阅所有示例。
功能说明
处理 WhatsApp、Messenger、Email、SMS 和 Voice 消息的状态更新。开始之前
- 在您的应用程序中创建一个公开的 HTTPS 端点。
- 为您需要的事件类型配置 YCloud Webhook 端点。
- 安全存储端点签名密钥。
- 确保事件处理具备幂等性。
工作原理
当事件发生时,YCloud 会发送一个 HTTPPOST 请求。验证签名,持久化记录该事件,返回 2xx 响应,并异步处理耗时任务。
请求
以下场景展示了发送至您的 Webhook URL 的请求。将事件id 视为传递标识符,并使用 type 路由有效负载。
响应
接收事件后返回2xx 状态。
有关端点设置、签名验证和重试机制,请参阅配置 Webhook。
accepted。消息状态更新将触发 whatsapp.message.updated Webhook。
通常,消息状态的变化规律如下:
- 如果我们无法送达该消息,状态将变为
failed。 - 如果可以送达该消息,状态将变为
sent,随后可能会变为failed、delivered或read。 - 如果该消息已成功送达收件人的设备,状态将变为
delivered或read。
delivered 事件可能会发生在 failed 之后,反之亦然,特别是在最终用户使用多个设备的情况下。
最高出价(Max Price)消息已送达
使用已送达消息的更新来对账最高出价(Max Price)营销消息的最终费用。请求
响应
持久化接收事件后返回2xx 响应。
说明
bidPricingFlag: true 和 pricingCategory: marketing_lite_bidding 标识出价模式。在处于 delivered 或 read 时,使用 totalPrice 和 currency 作为最终费用。配置的 maxBid 为价格上限;在 accepted 或 sent 报告的金额为预估值。有关配置和倍数示例,请参阅 Max Price 集成指南。
消息已发送
在此情况下,您的 Webhook 端点收到了消息sent 事件:
- 消息
status为sent,表示消息正在 WhatsApp 系统内部传输。 - 包含会话信息,包括会话过期时间以及发起来源类型。
- 包含我们可能向您收取的 预估
pricingCategory和totalPrice。 - 包含
wamid,即 WhatsApp 平台上的原始消息 ID,以wamid.开头。
请求
响应
持久化接收事件后确认投递。说明
-
totalPrice仅为首条消息送达前的预估价格,当status变为delivered或read时,该价格会成为最终价格。已发送但尚未送达的消息所占用的余额,在消息被丢弃前将不可用(已发送但超过 30 天未送达的消息会被丢弃)。 -
通常,处于
sent状态的消息很快会变为delivered或read,但以下情况除外:- 收件人的 WhatsApp 账户处于离线状态,您发送的 WhatsApp 消息将在收件人拥有可用或活跃的网络连接后才会送达。
- 发送给已将您拉黑的联系人的任何消息将始终显示为
sent,且绝不会变为delivered。 - 收件人已关闭已读回执,您将不会收到消息
read回执。 - 消息随后变为
failed并带有错误码131026,这表示“消息无法送达”或“接收方无法接收此消息”。这极有可能是因为收件人未注册,或者正在使用过旧的 WhatsApp 版本。 - 为保障高质量的用户体验,该消息未被送达。请参阅每个用户的营销模板消息限制。
消息已送达
在此情况下,您的 Webhook 端点收到了消息delivered 事件:
- 消息
status为delivered,表示消息已成功送达收件人的设备。
请求
响应
持久化接收事件后确认投递。说明
- 此事件表示您的企业发送的消息已送达至用户的设备。
- 状态要变为
read,必须先经历delivered。在某些场景中,例如用户正处于聊天界面且有新消息到达时,消息几乎同时变为delivered和read。在这种情况或类似场景下,系统不会返回delivered通知,因为消息已被读取即意味着已被送达。这种行为是出于内部优化原因。 - 针对同一条消息,我们可能会生成 1 个以上的
deliveredWebhook 事件,尤其是当最终用户使用多台设备时。 - pricingModel:“PMP”—— 表示按消息计费。另请参阅 whatsapp-message-pricing-updates
- pricingType
- regular — 表示该消息计费。
- free_customer_service — 表示该消息免费,因为它是客服时间窗口内发送的效用消息模板或非模板消息。
- free_entry_point — 表示该消息免费,因为它是免费入口点对话的一部分。
消息已读
在此情况下,您的 Webhook 端点接收到了消息read 事件:
- 消息
status为read,表示消息已被收件人读取。
请求
响应
在持久化接收该事件后确认投递。说明
- 如果收件人关闭了已读回执,您将不会收到消息
read回执。
消息发送失败
在此情况下,您的 Webhook 端点接收到了消息failed 事件:
- 消息
status为failed。 - 包含
errroCode、errorMessage和whatsappApiError。
请求
响应
在持久化接收该事件后确认投递。说明
- 这些事件旨在向您通知之前发送给客户的出站消息的状态变更。
- 消息发送失败的原因通常是消息请求参数无效、客户的电话号码未注册等。有关错误处理,请参阅 WhatsApp Errors。
- 如果我们曾尝试将此消息提交至 Meta 的 WhatsApp 平台,则会提供
whatsappApiError以帮助您了解错误详情。另请参阅 Cloud API Error Codes。 - 我们不会对失败的消息向您收费。
邮件投递更新
当邮件投递状态变更为delivered 或 failed 时,使用 email.delivery.updated。
请求
响应
在持久化接收该事件后确认投递。说明
使用emailId 和 recipientAddress 关联投递:该状态适用于此收件人。提供 externalId 时,可使用它来匹配您自己的记录。投递失败时请检查 errorCode 和 errorMessage。载荷属性为 emailDelivery,而非 whatsappMessage。
SMS 投递更新
当 SMS 投递状态变更为delivered 或 undelivered 时,使用 sms.message.updated。
请求
响应
在持久化接收该事件后确认投递。说明
通过sms.id 识别 SMS 并读取 sms.status。投递失败时请检查 errorCode。SMS 使用 undelivered 表示失败投递回执;请勿将 WhatsApp read 状态模型应用于此事件。
语音投递更新
当语音消息状态变更为delivered 或 undelivered 时,使用 voice.message.updated。
请求
响应
在持久化接收该事件后确认投递。说明
通过voice.id 识别语音消息并读取 voice.status。提供 errorCode 时请进行检查。此投递事件属于语音消息 API;它与 WhatsApp 通话生命周期事件相互独立。
Messenger 出站已读快照
订阅messenger.message.updated 以获取已保存的常规一对一出站快照。投递重试会保留 Event.id;从相同的源事实重新创建事件可能会产生新的 Event.id。请按 messengerMessage.id 关联更新。
提交与回执状态
accepted 表示 Meta 已接受提交,并不意味着消息已 sent 或 delivered。rejected 是明确的提交拒绝;unknown 是未确认的结果,绝不能视为失败。超时或出现 unknown 结果后,请勿自动重新提交消息。如有返回的消息 ID,请使用该 ID 检查其保存的状态,或联系支持人员。
快照会保留当前保存的事实,其中 read 优先于 delivered、sent 以及提交结果。迟到的回执不会降级该状态。您可能会收到重复的快照或遗漏中间状态。请将 GET /v2/messenger/messages/{id} 与 from 结合使用,或通过已确认的 Meta 消息 ID 进行检索,以对帐您当前保存的状态。
提交结果通知为尽力而为。请勿依赖针对每次同步发送结果都接收到 webhook。可选 ID、errorCode 以及回执时间在不可用时会被省略。在后续回执事实确立了更确定的状态后,已存储的提交错误可能仍然存在。
请求
响应
说明
Facebook Page ID 为from,客户 PSID 为 to。此示例展示了保存的 read 状态,且未捏造缺失的 sendTime 或 deliverTime。id 是 YCloud 消息 ID,而 metaMessageId 则是提供商标识。
Messenger 消息回应
请求
响应
说明
使用pageId 和 psid 来标识会话,并使用 metaMessageId 来标识目标消息。回应(reaction)属于互动行为,不会改变送达状态。目标消息可能没有本地 YCloud 消息记录。请保留源 createTime;可能会发生重复推送。在返回成功响应之前,请针对原始请求体验证 YCloud-Signature。
Messenger 消息回应已撤回
请求
响应
说明
移除与此 Page、客户 PSID 和目标 Meta 消息关联的回应。unreact 可以省略 reaction 和 emoji。不要强制要求本地消息 ID,也不要推断消息状态已发生变化。HTTP 推送重试会保留相同的事件 ID 和请求体;重复的源回调可能会生成新的事件 ID。在返回成功响应之前,请针对原始请求体验证 YCloud-Signature。
