Skip to main content
如需查看基于 Schema 生成的完整目录,请参阅所有示例。

功能说明

处理 WhatsApp、Messenger、Email、SMS 和 Voice 消息的状态更新。

开始之前

  • 在您的应用程序中创建一个公开的 HTTPS 端点。
  • 为您需要的事件类型配置 YCloud Webhook 端点。
  • 安全存储端点签名密钥。
  • 确保事件处理具备幂等性。

工作原理

当事件发生时,YCloud 会发送一个 HTTP POST 请求。验证签名,持久化记录该事件,返回 2xx 响应,并异步处理耗时任务。

请求

以下场景展示了发送至您的 Webhook URL 的请求。将事件 id 视为传递标识符,并使用 type 路由有效负载。

响应

接收事件后返回 2xx 状态。
有关端点设置、签名验证和重试机制,请参阅配置 Webhook。
对于 WhatsApp,在成功请求 API 发送消息后,消息的状态为 accepted。消息状态更新将触发 whatsapp.message.updated Webhook。 通常,消息状态的变化规律如下:
  • 如果我们无法送达该消息,状态将变为 failed。
  • 如果可以送达该消息,状态将变为 sent,随后可能会变为 failed、delivered 或 read。
  • 如果该消息已成功送达收件人的设备,状态将变为 delivered 或 read。
但实际情况往往更加复杂。首先,我们不保证 Webhook 通知到达的顺序,尤其是在事件几乎同时发生时。其次,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 个以上的 delivered Webhook 事件,尤其是当最终用户使用多台设备时。
  • 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。