WhatsApp Business Cloud API：消息已接受但未送达问题排查

请求详情 #

• 请求URL：

  POST https://graph.facebook.com/v20.0/<phone_number_id>/messages
  

• 请求体：

  {
      "messaging_product": "whatsapp",
      "recipient_type": "individual",
      "to": "<Mobile Number>",
      "type": "template",
      "template": {
          "name": "booking_details",
          "language": {
              "code": "en"
          },
          "components": [
              {
                  "type": "body",
                  "parameters": [
                      {"type": "text", "text": "chennai"},
                      {"type": "text", "text": "salem"},
                      {"type": "text", "text": "tn15505"},
                      {"type": "text", "text": "star"},
                      {"type": "text", "text": "23.02.2024"},
                      {"type": "text", "text": "koyambedu"},
                      {"type": "text", "text": "bus stand"},
                      {"type": "text", "text": "10:00 a.m."},
                      {"type": "text", "text": "₹5055"},
                      {"type": "text", "text": "L1/S,L2/S"}
                  ]
              },
              {
                  "type": "button",
                  "sub_type": "quick_reply",
                  "index": "0",
                  "parameters": [
                      {
                          "type": "payload",
                          "payload": "PAYNOW_PAYLOAD"
                      }
                  ]
              },
              {
                  "type": "button",
                  "sub_type": "quick_reply",
                  "index": "1",
                  "parameters": [
                      {
                          "type": "payload",
                          "payload": "CHANGE_DETAILS_PAYLOAD"
                      }
                  ]
              }
          ]
      }
  }
  

响应内容 #

{
    "messaging_product": "whatsapp",
    "contacts": [
        {
            "input": "receiver",
            "wa_id": "id"
        }
    ],
    "messages": [
        {
            "id": "wamid.HBgMOTE4MDU2MTg1NjI5FQIAERgSMUQwQzU3MjVENDBBMEQ5NTk5AA==",
            "message_status": "accepted"
        }
    ]
}

已尝试操作 #

• 验证模板已获批且名称匹配
• 确认收件人手机号已注册WhatsApp
• 确保phone_number_id和访问令牌正确
• 检查收件人已同意接收消息
• 确认WhatsApp商业账户无低质量评级或速率限制

可能原因及排查解决方法 #

可能原因 #

1. 模板结构不匹配：请求中的组件（body参数数量、按钮类型/索引）与Meta后台获批的模板不一致，导致消息无法正常渲染。
2. 号码格式不规范：收件人号码未严格遵循E.164标准（如缺少国家码、含非数字符号），API虽接受请求，但WhatsApp无法路由到目标用户。
3. 内容过滤拦截：填充的参数内容触发WhatsApp的内容安全机制，即使模板获批，敏感或违规内容仍会被拦截。
4. 语言代码不匹配：模板的语言版本（如en_US）与请求中传入的code（如en）不兼容，导致模板无法匹配。
5. 消息处理延迟：WhatsApp服务器负载或网络问题导致消息延迟送达，并非完全失败。

排查步骤 #

• 核对模板结构：在Meta Business Manager中打开booking_details模板，逐一确认body占位符数量、按钮类型（quick_reply）及索引是否与请求体完全对应。
• 简化测试：暂时移除按钮组件，仅发送body部分，测试是否能送达，定位问题出在body还是按钮。
• 规范号码格式：将收件人号码转换为纯数字E.164格式（如+911234567890），重新发送测试。
• 配置Webhook监听：设置监听message_status事件的Webhook，查看消息后续状态（如failed会返回具体错误码），明确失败环节。
• 测试基础模板：用一个已获批的简单纯文本模板（无按钮）发送给同一收件人，排除账户或路由问题。
• 查看账户日志：在Meta Business Manager的WhatsApp账户模块中，查看消息发送日志，获取官方错误提示。

内容的提问来源于stack exchange，提问作者JustVy Global Innovations