登录开始免费试用
Meta Tech Provider

WhatsApp 状态 Webhook:已发送、已送达、已读与失败

状态 webhook 报告通过 WhatsApp Cloud API 发送的消息发生了什么。它们通过 messages 字段到达,但内容是 statuses 数组而非 messages 数组:已发送(一个勾)、已送达(两个勾)、已读(两个蓝勾)、语音消息已播放,以及带有 errors 数组的失败。将 statuses[].id 与发送请求返回的 wamid 匹配。

easyCoexistence 通过 Coexistence 将您已在使用的 WhatsApp Business 应用号码连接到 Meta 的 Cloud API。

5

Meta 发送的状态值有:sent、delivered、read、played(语音消息首次播放)和 failed。

3

一条外发消息可能产生的独立状态 webhook:sent、delivered 和 read。

v24.0

从此 Graph API 版本起,除免费入口窗口内的消息外,会省略 conversation 对象。

0

不存在用于获取历史 webhook 数据的 API;Meta 要求您在负载到达时即捕获并存储。

messages

转发的状态上带有 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 服务器的营销模板:

Meta's example: a marketing message with status sent
{
  "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,并且应对状态进行排序,而不是假定它们会按固定顺序逐一出现。

sentLeft Meta's servers. One gray check in WhatsApp.
deliveredReached the customer's device. Two gray checks.
readDisplayed in an open chat on the device. Two blue checks.
playedFirst play of voice messages. Blue microphone.
failedCould not be sent or delivered. Red error triangle, plus an errors array.

状态对象包含哪些字段?

字段比消息少,而且其中多个是有条件出现的。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 status webhooks to your sends (Node.js)
// 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 中。
使用 EasyCoexistence 完成这些操作

您的自动化、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,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间