登录开始免费试用
Meta Tech Provider

WhatsApp API 消息未送达:原因按排查顺序列出

已接受的 WhatsApp API 消息不等于已送达:Meta 会随后通过状态 Webhook 报告结果,即已发送、已送达、已读或失败,失败时附带错误代码。请依次检查:失败状态及其代码、24 小时窗口(131047)、付款方式(131042)、模板(132001、132015)、收件人(131026、131049、131050),最后检查号码的限制与连接。

easyCoexistence 全天候监控每个已连接号码,当 Meta 停止投递、断开连接或降低质量评级时向您发送邮件,并原样转发 Meta 的状态 Webhook 到您的系统。

4 statuses

sent(一个勾)、delivered(两个勾)、read(两个蓝勾)和 failed(红色错误三角形),即状态 Webhook 报告的状态。

131047

距离收件人上次回复已超过 24 小时;Meta 建议改为发送模板。

131026

无法送达的原因:号码未注册 WhatsApp、收件人未接受新条款,或使用的是旧版 WhatsApp。

30 days

WhatsApp 在放弃前重试未送达的实用类或营销类模板的默认时长;认证类模板默认为 10 分钟。

20 mps

同时用于 WhatsApp Business 应用和 Cloud API 的号码,其吞吐量是固定的。

为什么已接受的消息仍未到达?

因为 API 响应与送达是两个独立事件。发送时,Meta 一接受请求就会返回消息 ID;消息是否到达客户手机,则稍后通过 messages 字段上的状态 Webhook 告知。sent 表示已离开 Meta 服务器(一个勾),delivered 表示已到达设备(两个勾),read 表示已被打开(两个蓝勾),failed 表示无法发送或投递,并通过 errors 数组向您显示:code、title 和 error_data.details。因此首先不要猜测:查找该消息 ID 的 failed 状态,并读取其代码。若您没有设置 Webhook 接收地址,系统将不会记录这些状态。

原因有哪些?请按排查顺序查看。

从新连接号码上最常见的原因,到最少见的原因排列。每一项都注明 Meta 的代码,方便您根据 failed 状态判断属于哪一类:

  • 窗口已关闭:131047,距离客户上次发消息已超过 24 小时。自由文本消息需要处于开放的窗口期内,请改为发送模板。
  • 付款:131042,或模板被静默丢弃。自 2026 年 10 月 1 日起,若未添加付款方式,每月使用满 1,000 条后,服务类消息也会停止发送。
  • 模板:132001 未获批准或语言错误,132000 变量数量错误,132012 格式错误,132015 已暂停,132016 已停用。
  • 收件人:131026 未注册 WhatsApp、版本过旧或未接受条款;131050 已停止接收营销消息;131049 因保持良好互动而被暂缓;发送给美国号码的营销模板不会送达。
  • 限制:131048 因垃圾信息信号而受限,131056 发给同一人的消息过多,130429 吞吐量超限;Coexistence 号码每秒 20 条消息。
  • 账户:131031 或 368,因违反政策,WhatsApp Business 账户受限或被停用。
  • 连接:号码已不再关联,例如连续 14 天未打开 WhatsApp Business 应用后。

如何处理收件人端的错误代码?

需区别对待,因为有些代码值得重试,有些则永远不应重试。131050 表示该用户已选择停止接收您的营销消息:Meta 建议不要重试,而 user_preferences Webhook 会告知您用户何时停止或恢复接收。131049 是 Meta 为保持良好互动而暂缓的营销消息,通常是对营销模板设有的单用户限制:Meta 建议至少等待 24 小时后再重新发送,因为过早重发只会再次返回相同错误。131026 涵盖号码未注册 WhatsApp、用户未接受 WhatsApp 当前条款以及应用版本过旧的情况;请先检查号码格式和国家/地区代码,然后通过其他渠道联系客户。

WhatsApp 会尝试送达多久?

在消息的存活时间(TTL)内持续尝试。当手机关机或信号中断时,WhatsApp 不会立即判定失败,而是持续重试:实用类和营销类模板默认为 30 天,认证类模板默认为 10 分钟。商家可通过 message_send_ttl_seconds 按模板缩短该时间:实用类为 30 秒至 12 小时,认证类为 30 秒至 15 分钟。在 TTL 内无法送达的消息将被丢弃。因此,若消息已显示 sent 状态,却在数小时后仍无 delivered 状态,通常说明它正在等待客户手机接收,而非丢失。请为验证码和时效性提醒设置较短的 TTL,以免延迟送达造成混淆。

这对 AI 回复和自动化意味着什么?

先看运行记录,再看状态。在“Runs”标签页中,Skipped 运行未发送任何内容,并会说明原因:“More than 24 hours since the customer's last message”、“You answered this chat from your phone recently”或“AI reply limit for this chat reached this hour”。Done 运行表示 Meta 已接受每条回复,但这并不等于已送达。easyCoexistence 不存储消息状态:若开启自动化并设置了转发 URL,状态会发送至该 URL;在直连模式下,状态则直接发送至您自己的端点。若您使用 ChatGPT 或 Claude,可让 AI 运行 get_number_health:它会返回实时状态、质量评级,以及最近 15 条监控事件,其中包括含 Meta 代码的 sending 块。

设置方法

  1. Find the statusLook up the message id in your webhook log and read the latest status: delivered, read, sent only, or failed with an error code.
  2. Match the codeLook up the failed status's code in the list of causes above and in Meta's error codes reference.
  3. Check the accountConfirm the WhatsApp Business Account has a default payment method, a currency and a time zone in Billing & payments.
  4. Check the templateIf it was a template, confirm it is APPROVED in that language and the variables match its definition.
  5. Check the numberAsk your AI to run get_number_health, or open the number in the dashboard, to see the connection and any sending block.

常见错误

  • 对 131050 进行重试。该用户已停止接收您的营销消息;再多次尝试也无法送达,反而可能增加负面信号。
  • 把消息 ID 当作已送达。Meta 先接受请求,稍后才报告失败,因此停在消息 ID 的工作流会漏掉每一条被拒绝的消息。
  • 一天后才发送自由文本回复。客户超过 24 小时未发消息后,只有模板会被接受。
  • 没有设置 Webhook 接收地址就运行。失败状态仅以 Webhook 形式送达,若没有接收地址,消息未送达的原因就会丢失。
使用 EasyCoexistence 完成这些操作

您的 AI 可通过 get_number_health 从 ChatGPT 或 Claude 检查号码。每个已连接号码每月 US$ 9 起,号码越多单价越低,最低降至 US$ 0.75,前 3 天免费试用。

常见问题

为什么消息显示一个勾很久?

一个勾表示 sent 状态:Meta 已发出,但手机尚未收到,通常是因为手机关机或离线。WhatsApp 会持续重试,直到模板的存活时间用完,实用类和营销类默认为 30 天。

为什么回复能送达,模板却不能?

通常是 WhatsApp Business 账户的付款方式出了问题。在号码每月免费额度内,Meta 即使没有付款方式也会投递服务类消息,但不会投递模板。请在“账单与付款”中添加银行卡。

能否在 WhatsApp Business 应用中查看失败的消息?

不可靠。在 Coexistence 号码上,通过 API 发送的消息会出现在应用的聊天线程中,但消息失败的原因只能通过状态 Webhook 中的错误代码查看。

对于未送达的消息,Meta 会收费吗?

不会。Meta 只对已送达的消息收费,使用已暂停模板发送的尝试同样不收费。

继续阅读

准备开始了吗?

几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间