WhatsApp Messages API 最佳实践

​

准备工作

• 连接并注册用于发送消息的 WhatsApp 商业电话号码。
• 在服务器端妥善保存您的 YCloud API Key。
• 为 whatsapp.message.updated 配置带签名的 Webhook 端点。
• 定义系统如何记录用户许可、退订请求、消息用途以及数据留存策略。
• 指定消息发送、Webhook 处理及突发事件响应的负责人。

​

选择发送端点

​

创建内部发送记录

​

将响应与状态 Webhook 关联

​

1. 发送消息

curl --request POST https://api.ycloud.com/v2/whatsapp/messages \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "template",
    "externalId": "order-ready-10001",
    "filterUnsubscribed": true,
    "filterBlocked": true,
    "template": {
      "name": "orders_pickup_ready_v2",
      "language": {
        "code": "en_US",
        "policy": "deterministic"
      }
    }
  }'

​

2. 存储已接受的响应

{
  "id": "MESSAGE_ID",
  "wabaId": "WHATSAPP_BUSINESS_ACCOUNT_ID",
  "from": "+16315551111",
  "to": "+16315552222",
  "type": "template",
  "status": "accepted",
  "externalId": "order-ready-10001",
  "createTime": "2026-08-27T09:00:00.000Z"
}

​

3. 应用后续状态事件

{
  "id": "evt_MESSAGE_STATUS_1",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-27T09:00:02.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "externalId": "order-ready-10001",
    "sendTime": "2026-08-27T09:00:01.000Z"
  }
}

​

构建收敛状态模型

1. 使用原始请求体验证 Webhook 签名。
2. 持久化存储事件，使用事件 id 作为去重键。
3. 及时返回 2xx 响应，然后异步处理事件。
4. 将 whatsappMessage.id 与内部发送记录进行匹配。
5. 存储事件状态及其可用的消息时间戳。保留审计所需的原始事件元数据，但移除不必要的消息内容。
6. 更新当前业务视图，且不丢弃冲突或后续的凭证。即使没有收到单独的 delivered 事件，也将 read 视为消息已投递的证据。
7. 当事件冲突、终态超出服务目标仍未达到或 Webhook 管道不可用时，检索 GET /whatsapp/messages/{id}。

​

重试时不产生重复发送

• 锁定或原子性地认领内部业务主键。
• 检查该记录是否已拥有 YCloud id 或状态事件。
• 不要使用新的 externalId 来掩盖早期不明确的尝试。
• 在达到配置的尝试次数或时长限制后停止。
• 在重放不明确的发送前，需要操作员明确执行操作。

​

选择模板和会话消息

​

高效处理媒体

• 在上传前验证文件支持的 MIME 类型和大小。对于超大或不受支持的文件， 请勿在未做更改的情况下重试。
• 使用将要发送消息的商业电话号码进行上传。
• 在返回的媒体 ID 有效期内，重复发送同一已获批素材时可复用该 媒体 ID。上传的媒体文件将保留 30 天。
• 存储素材校验和、MIME 类型、媒体 ID、发送者和过期时间， 以避免工作节点为每个收件人重复上传相同文件。
• 过期后或发送者上下文发生变更时重新上传。
• 当消息结构要求提供链接时（包括互动消息标头中的媒体）， 请改用公开 URL。
• 从存储流式传输大文件上传，设置请求超时，并在使用后删除 本地临时文件。

​

执行授权许可并最小化数据

​

控制批量吞吐量

• 429 响应
• 请求延迟和超时
• 5xx 响应
• 队列堆积时长或重试积压
• Webhook 延迟和未解决的 accepted 消息

​

常见反模式

• 当 API 返回 accepted 时即标记消息已送达。
• 将 externalId 视为 YCloud 幂等性密钥。
• 对所有非 2xx 响应或超时进行无限制重试。
• 对所有流量均使用 sendDirectly。
• 假定 Webhook 具有唯一性、有序性或完整性。
• 在客户服务窗口期外发送自由格式消息。
• 为每个接收者重复上传相同的媒体文件。
• 仅依赖抑制过滤器而未记录用户同意信息。
• 记录 API 密钥、完整负载或不必要的个人数据。
• 以无限制并发且缺乏背压控制的方式启动批处理。

​

上线前检查清单

• 终端节点的选择符合工作负载和延迟要求。
• 数据库唯一性规则保护了内部业务键。
• externalId、YCloud id 以及 wamid 各自具有明确记录的职责。
• 在收到状态凭证之前，初始响应保持为非最终状态。
• Webhook 签名、事件去重、快速确认响应及重放机制均已通过测试。
• 配置了定时拉取任务以对账延迟或丢失的事件。
• 可重试和不可重试的失败均具有受限的处理路径。
• 发送前严格执行模板规则与会话窗口规则。
• 媒体上传经过校验、复用、过期管理并能安全清理。
• 同意记录、退订、阻止列表、保留策略与日志记录管控均已核实。
• 批处理队列具备并发限制、背压机制、监控面板与告警设置。
• 运维人员可以暂停发送并审核状态不确定的尝试，而不会自动重放它们。