Skip to main content
发送请求和送达消息是两个不同的事件。成功的 API 响应仅确认该阶段的请求结果；并不保证客户已收到或已阅读该消息。 使用 YCloud 消息状态和所有可用的错误详情来了解具体情况。

​
出站消息状态

YCloud 出站 WhatsApp 消息资源使用以下状态： 典型的成功流转过程为 accepted → sent → delivered → read。请勿假设应用程序会收到每个中间更新，也不要假设更新会完全按该顺序到达。

​
为什么请求成功不代表最终送达

使用排队端点时，YCloud 会接受请求并异步提交。使用直接端点时，提交到 WhatsApp Business API 是同步进行的。在这两种情况下，最终送达仍然是异步的。 有关实现详情，请参阅发送 WhatsApp 消息。 如果当前状态仍为 accepted 或 sent，请勿重复提交相同内容。额外的请求可能会导致消息重复。

​
送达回执与已读回执

已送达表示消息已到达客户设备，并不意味着客户打开了对话。 已读回执并非在所有情况下都可用。例如，客户的已读回执设置会影响是否报告已读更新。未收到已读更新并不能证明客户忽略了该消息。 有关上游状态定义，请参阅 Meta 的消息状态 Webhook 参考。

​
跨系统跟踪同一条消息

进行排查时，请保留以下相关信息： 共享排查记录时，请勿包含 API 密钥或不必要的客户信息。 API 集成可以接收 whatsapp.message.updated Webhook 并检索消息资源。有关同步和重试处理，请参阅WhatsApp 消息发送最佳实践。

​
排查失败的消息

请从返回的错误入手，而不仅凭状态名称。
  • 模板问题： 确认消息模板可用，且其语言和参数正确。
  • 服务窗口问题： 检查消息是否需要处于开启状态的客户服务窗口。
  • 账户或号码问题： 检查受影响的资产及其当前限制。
  • 内容或媒体问题： 检查所选消息类型的要求。
  • 送达控制： 遵循具体的错误指导。立即重复重试可能无法解决平台限制。
消息失败并不能断定客户已屏蔽您的号码。请使用实际的错误详情，避免推测平台未报告的客户行为。 有关平台送达控制，请参阅质量与送达控制。有关违规处置通知，请参阅账户限制与申诉。

​
判断重试是否安全

良好的消息记录会将单个预期业务操作与其请求和结果绑定。您的外部引用有助于关联，但除非端点明确保证了幂等行为，否则请勿假定其提供 API 幂等性。

​
状态更新延迟示例

您的系统先收到 delivered，随后收到了同一消息延迟到达的 sent 事件。切勿将客户的状态改回“未送达”。请存储事件时间戳，并应用能够容忍重复和乱序更新的状态模型。 同样，缺少 read 事件并不代表消息发送失败。请区分以下指标：
  • 送达触达： 具有送达证据的消息。
  • 已读触达： 报告了已读回执的消息。
  • 客户响应： 实际的入站回复或互动。
  • 业务转化： 在所属系统中确认的预订、购买或成功验证。

​
后续步骤

​
常见问题解答

无法得出该结论。已读回执可能不可用，包括接收方禁用该功能的情况。请将送达和已读作为独立的指标。无论是缺少已读回执还是常规的无法送达错误，都无法确定客户的具体原因或证明被拉黑。
不能立即重发。平台可能已经接受了该请求。在发起另一次发送前，请检查消息标识符、可用日志以及后续的 Webhook 事件。将重试关联到同一个业务操作并设计防重机制；外部引用并不自动等同于端点幂等性保证。
显示限制与送达失败是两回事。请检查实际的方向、状态、消息类型以及任何错误。对于入站内容，请参阅收件箱不支持的消息指引；切勿猜测内容或将占位符视为出站发送失败。