处理 WhatsApp 入站消息

​

功能介绍

​

准备工作

• 为 whatsapp.inbound_message.received 配置 Webhook 端点。
• 在处理事件前验证 YCloud-Signature 请求头。
• 存储入站消息 id。
• 连接接收消息的商业电话号码。

​

工作原理

1. 接收并验证 Webhook 事件。
2. 通过事件 id 对事件进行去重。
3. 提取入站消息 id 和内容。
4. （可选）将消息标记为已读。
5. 仅在正在准备回复时显示输入指示器。
6. 使用 WhatsApp Messages API 发送回复。

​

请求

​

将消息标记为已读

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/inboundMessages/INBOUND_MESSAGE_ID/markAsRead \
  --header "X-API-Key: $YCLOUD_API_KEY"

​

显示输入指示器

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/inboundMessages/INBOUND_MESSAGE_ID/typing \
  --header "X-API-Key: $YCLOUD_API_KEY"

​

响应

HTTP/1.1 200 OK

​

处理指南

• 在开始耗时的 AI 或业务处理之前确认（Acknowledge）Webhook。
• 如果您的业务场景依赖消息顺序，请保持每个会话的消息顺序。
• 显式处理每种受支持的入站 type，并保留不受支持的 有效负载以供排查。
• 回复特定入站消息时使用消息上下文。

​

限制与排错

• 除非随后会发送回复，否则不要显示输入指示器。
• 在操作路径中使用入站消息 ID，而不是 Webhook 事件 ID。
• 确保 Webhook 处理具有幂等性，因为消息投递可能会重试。
• 如果操作失败，记录 YCloud requestId，不要记录消息 内容或凭据。