WhatsApp 状态 Webhook:已发送、已送达、已读与失败
状态 webhook 报告通过 WhatsApp Cloud API 发送的消息发生了什么。它们通过 messages 字段到达,但内容是 statuses 数组而非 messages 数组:已发送(一个勾)、已送达(两个勾)、已读(两个蓝勾)、语音消息已播放,以及带有 errors 数组的失败。将 statuses[].id 与发送请求返回的 wamid 匹配。
easyCoexistence 通过 Coexistence 将您已在使用的 WhatsApp Business 应用号码连接到 Meta 的 Cloud API。
Meta 发送的状态值有:sent、delivered、read、played(语音消息首次播放)和 failed。
一条外发消息可能产生的独立状态 webhook:sent、delivered 和 read。
从此 Graph API 版本起,除免费入口窗口内的消息外,会省略 conversation 对象。
不存在用于获取历史 webhook 数据的 API;Meta 要求您在负载到达时即捕获并存储。
转发的状态上带有 X-EC-Event 标头:状态在 messages 事件中传递,位于 value.statuses 之下。
WhatsApp 状态 webhook 在哪里到达?
它们与客户发来消息所用的是同一个 messages 字段,位于相同的 object、entry 和 changes 结构中。区别在于 value 内部:入站消息包含 messages 数组,状态则包含 statuses 数组。只读取 value.messages 的处理程序会悄无声息地丢弃所有状态,且不报错。metadata.phone_number_id 标明哪一个号码发送了该消息。此外还会附带 contacts 数组,其中包含客户的个人资料名称、wa_id 和 BSUID,但失败状态以及群组消息的已发送状态除外。以下是 Meta 的示例,展示一条已离开 Meta 服务器的营销模板:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Pablo M."
},
"wa_id": "16505551234",
"user_id": "US.13491208655302741918"
}
],
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"status": "sent",
"timestamp": "1750030073",
"recipient_id": "16505551234",
"recipient_user_id": "US.13491208655302741918",
"conversation": {
"id": "72b14d6bd5407799e66f64d1b338e567",
"expiration_timestamp": "1750116480",
"origin": {
"type": "marketing"
}
},
"pricing": {
"billable": true,
"pricing_model": "PMP",
"type": "regular",
"category": "marketing"
}
}
]
},
"field": "messages"
}
]
}
]
}每个状态值代表什么?
每个值都对应客户在 WhatsApp 中看到的一个标记。只有在消息已送达之后,状态才算已读;当客户在聊天窗口已打开时收到消息,Meta 会出于内部优化直接发送 read,而不先发送 delivered webhook。因此,追踪程序应接受 read,即使从未收到 delivered,并且应对状态进行排序,而不是假定它们会按固定顺序逐一出现。
状态对象包含哪些字段?
字段比消息少,而且其中多个是有条件出现的。Meta 参考文档列出了每个字段出现的条件:
- id:您所发送消息的 wamid,即用于匹配的键。
- status 和 timestamp:状态值,以及触发 webhook 的 Unix 时间(以字符串形式表示)。
recipient_id:电话号码或群组 ID;当您发送至 BSUID 且号码不可用时省略。recipient_user_id:客户的 BSUID;当您发送至电话号码时,失败状态中省略。recipient_type和recipient_participant_id:仅用于发送至群组的消息。biz_opaque_callback_data:仅当您在发送请求中设置了该字段时出现。- pricing:仅出现在 sent,以及 delivered 或 read 之一上;errors:仅出现在 failed 上。
如何将状态与您发送的消息匹配?
通过 wamid。发送请求会返回 messages[0].id,该消息的每个状态都在 statuses[].id 中带有相同的值。发送时请将其与您自己的记录一同保存,收到状态后更新该记录,并保留已达到的最高状态,这样较晚到达的 delivered 就不会覆盖 read。如果某个状态的 wamid 不在您的记录中,说明该消息是号码上的其他程序发送的,例如某个自动化流程,可忽略或记录下来。
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };
// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
for (const s of value.statuses ?? []) {
const rec = sends.get(s.id); // the wamid your send request returned
if (!rec) continue; // sent by something else, such as an automation
if (s.status === "failed") {
rec.status = "failed";
rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
} else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
rec.status = s.status; // read arriving before delivered is fine; never step back
}
rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
}
}Coexistence 号码会有什么变化?
状态描述的是通过 API 发送的内容:您的自动化回复、您的 AI 通过 MCP 连接器发送的消息,以及您自己的代码发送的任何内容。您在 WhatsApp Business 应用中输入的内容,会以不同方式到达软件,即 smb_message_echoes,Meta 将其记录为应用所发消息的镜像。通过一次性历史导入而来的消息,其状态包含在历史 webhook 中,取值包括 delivered、read、played、pending 和 error。
状态会随号码的 messages 字段一同发送到相应位置。使用直连目标时,Meta 会直接将状态发送到您的端点,因为 messages 是 Meta 允许目标覆盖的字段。开启自动化并设置了转发 URL 后,状态会以 messages 事件的形式到达该 URL。
您的 AI 或自动化如何得知消息是否已送达?
通过您的接收目标,而不是通过发送操作本身。当助手调用 send_template 或 send_message 时,工具结果会携带 wamid,并表明 Meta 已接受该消息;送达会在客户设备上确认之后,再以状态形式稍后报告。easyCoexistence 不保存可供查询的状态历史,也没有任何 MCP 工具读取状态,因此需要送达确认的代理,应通过您自己的系统发送,或读取转发 URL 所接收的状态。
自动化同理:在运行记录标签中,回复步骤在 Meta 接受消息后即显示为已完成;之后报告的失败,只会作为 failed 状态出现在您的接收目标处。
常见错误
- 去寻找单独的 statuses 字段。状态出现在 messages 中,因此只读取 value.messages 的处理程序会在没有任何报错的情况下丢失它们。
- 要求必须先收到 delivered 才能处理 read。当消息到达即被读取时,Meta 会跳过 delivered webhook。
- 将发送响应当作送达。wamid 仅表示 Meta 已接受请求;失败可能在数分钟后以 failed 状态出现。
- 仅以 recipient_id 作为客户的键。当您发送至 BSUID 且电话号码不可用时,该字段会被省略;BSUID 位于 recipient_user_id 中。
您的自动化、AI 或代码所发送内容的状态,会直接从 Meta 发送到您的服务器(直连模式),或在开启自动化时转发至您的转发 URL,并以 X-EC-Signature 签名;默认不存储。每个号码每月 US$ 9 起,号码越多越便宜,最低降至 US$ 0.75,前 3 天免费试用。
常见问题
状态 webhook 是否包含消息正文?
不包含。状态包含 wamid、状态值、接收方、时间戳,以及适用时的计费和错误信息。如需在状态旁显示所发送的内容,请以 wamid 为键,保留您自己的发送副本。
之后能否从 Meta 获取历史状态?
不能。Meta 的 webhook 指南说明,不存在用于获取历史 webhook 数据的 API。因此,若您的端点未捕获某个状态,则在 Meta 停止重试(最多 7 天)后,该状态即无法再获取。
biz_opaque_callback_data 有什么用?
这是您在发送时设置的字符串,例如您自己的订单或工单编号。Meta 会在该消息的 statuses 中返回此字符串,因此您无需先查找 wamid,即可将状态与记录对应起来。
状态 webhook 是否必须以 200 响应?
是的,与任何 webhook POST 一样。Meta 会将其他任何响应视为投递失败并重试,这也是同一状态可能重复送达您的原因之一。
继续阅读
准备开始了吗?
几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间