接收 WhatsApp 回应
订阅回应变更，以便了解联系人何时对您的消息添加表情符号、更改表情符号或撤回表情符号。回应附加在现有消息上，通过 whatsapp.reacted 送达。
前提条件
为您的工作区设置一个 webhook 端点。要检索当前回应或其历史记录，请使用具有 WhatsApp 读取权限的 API 密钥。
1. 订阅回应变更
回应不会在消息列表中创建新消息，也不会打开客服会话窗口。如果您需要回复，请在发送自由格式消息之前查看服务窗口规则。
2. 识别消息和变更
读取事件的 data.whatsapp_id，找到联系人所回应的消息。这是原始 Bird 消息 ID (wam_…)，而非单独的回应 ID。
联系人添加一个竖起大拇指的回应会产生以下 webhook：
代码示例
{
"data": {
"emoji": "👍",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"whatsapp_id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
"workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
},
"timestamp": "2026-08-28T19:01:10.000Z",
"type": "whatsapp.reacted"
}按以下方式解读 data.emoji：
- 非空的表情符号表示在被引用的消息上添加或替换该联系人的回应。
- null 表情符号表示移除该联系人的回应。此字段在移除事件中存在。
替换以一个携带新表情符号的事件送达；旧表情符号没有单独的移除事件。请保留精确字符串：❤ 和 ❤️ 在载荷中是不同的值。
3. 检索当前回应
如果您的应用需要显示当前附加在消息上的回应，请检索该消息并读取其 reactions。该列表包含每个发送方的一个有效回应，当没有回应存在时会被省略。
对于 GET /v1/whatsapp/messages/wam_01ky8b3xq4gd7pmzn2ka51f7te，回应相关字段的结构如下（省略了其他消息字段）：
代码示例
{
"id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
"reactions": [
{
"emoji": "👍",
"from": { "phone_number": "+14155550100" }
}
]
}消息保留其原始内容、方向和投递状态。reactions[].from 标识做出回应的人。
不要将收到的最后一个 webhook 视为当前状态。WhatsApp 以秒为精度报告回应时间，因此变更可能共享同一时间戳，webhook 重试也可能改变到达顺序。请使用 webhook 触发对消息当前回应的刷新。
4. 查看回应历史
回应事件 API 返回分页响应。以下示例展示了一个被拒绝的业务回应和一个更早收到的联系人回应：
代码示例
{
"data": [
{
"id": "war_01krdgeqcxet5s7t44vh8rt9mh",
"emoji": "🎉",
"status": "rejected",
"from": {
"phone_number": "+13124495569"
},
"error": {
"code": "internal_error",
"description": "the receiving number is no longer connected",
"occurred_at": "2026-08-28T19:04:22Z"
},
"occurred_at": "2026-08-28T19:04:22Z"
},
{
"id": "war_01krdgeqcxet5s7t44vh8rt9mg",
"emoji": "👍",
"status": "received",
"from": {
"phone_number": "+14155550100",
"bsuid": "US.13491208655302741918"
},
"occurred_at": "2026-08-28T19:01:10Z"
}
],
"next_cursor": null,
"prev_cursor": null,
"refresh_cursor": "eyJ2IjoxLCJzIjoiMjAyNi0wOC0yOFQxOTowNDoyMloiLCJpIjoiMDE5ZTFiMDctNWQ5ZC03NjhiLTkzZTgtODRkYzUxOGQyNjkxIn0"
}回应历史与消息的投递事件是分开的。消息事件端点不包含 whatsapp.reacted 变更。关于保留期和分页方式，请参照回应日志参考。
故障排查
- 没有收到回应 webhook：检查订阅是否包含 whatsapp.reacted。对较旧消息的回应，如果其提供商引用已无法解析，则不会产生匹配的回应、日志条目或 webhook。
- 消息列表中缺少回应：查找原始消息。回应附加在该消息上，没有单独的消息行。
- 回应状态意外变化：刷新原始消息的 reactions，而不是按到达时间或时间戳对 webhook 事件排序。