WhatsApp Business API发送对话模板报错，重建模板仍未解决

问题背景 #

尝试通过WhatsApp Business API发送带文档附件的模板消息，即使删除并重建模板后仍持续报错。模板已通过Meta审核（状态为APPROVED），但发送时返回参数无效错误，提示HEADER参数需要符合手机号格式，与模板定义的DOCUMENT格式矛盾。

模板详情（Meta getAllTemplates API返回） #

{
    "name": "sned_document_2",
    "parameter_format": "POSITIONAL",
    "components": [
        {
            "type": "HEADER",
            "format": "DOCUMENT",
            "example": {
                "header_handle": [
                    "https://scontent.whatsapp.net/v/t61.29466-34/507975905_2175446719588384_6423190851307979730_n.pdf?ccb=1-7&_nc_sid=8b1bef&_nc_ohc=7InhT1d5VuYQ7kNvwEGEzCt&_nc_oc=AdmF8Lz8VnbZc1BSqv75EGamG5n4EQ34ywLetU-2icAJySI5hODxU9j_HVK__CqJh58&_nc_zt=3&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&_nc_gid=cMF4oT522xTDeOGE05j3eA&oh=01_Q5Aa1wHhIBiIILxEOflykwVeTGZQXs9f0G6QPaxHdylJijpw9A&oe=687C93B6"
                ]
            }
        },
        {
            "type": "BODY",
            "text": "Hello {{1}},\n\nYour invoice for order {{2}} is attached.\n\nThank you for shopping with us!",
            "example": {
                "body_text": [
                    [
                        "John",
                        "#12345"
                    ]
                ]
            }
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "URL",
                    "text": "Order details",
                    "url": "https://www.example.com/{{1}}",
                    "example": [
                        "https://www.example.com/home"
                    ]
                }
            ]
        }
    ],
    "language": "en_US",
    "status": "APPROVED",
    "category": "UTILITY",
    "library_template_name": "purchase_receipt_3",
    "id": "2175446716255051"
}

发送请求参数 #

{
    "messaging_product": "whatsapp",
    "to": "{{Recipient-WA-ID}}",
    "type": "template",
    "template": {
        "name": "sned_document_2",
        "language": {
            "code": "en_US"
        },
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "document",
                        "document": {
                            "link": "https://eppg.fgv.br/sites/default/files/teste.pdf",
                            "filename": "teste.pdf"
                        }
                    }
                ]
            },
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Carlos"
                    },
                    {
                        "type": "text",
                        "text": "#5234"
                    }
                ]
            },
            {
                "type": "button",
                "index": "0",
                "sub_type": "url",
                "parameters": [
                    {
                        "type": "text",
                        "text": "https://www.example.com/home"
                    }
                ]
            }
        ]
    }
}

返回错误信息 #

{
    "error": {
        "message": "(#100) Invalid parameter",
        "type": "OAuthException",
        "code": 100,
        "error_data": {
            "messaging_product": "whatsapp",
            "details": "For component HEADER, parameter '' does not have a valid phone_number format. Length Limit is 20 characters and detailed format requirements can be found at https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates/utility-templates#template-parameters-and-restrictions."
        },
        "fbtrace_id": "A4Ttv49GliSIrCDFRzRBuXr"
    }
}

错误分析 #

错误提示与模板定义矛盾：模板明确将HEADER设置为DOCUMENT格式，但API返回错误要求参数符合手机号格式，大概率是以下原因：

• Meta模板系统缓存：删除重建模板后，服务器端缓存未及时更新，导致API仍读取旧的模板配置
• 模板实际配置与API返回不一致：Meta Business Manager中模板的HEADER参数类型可能被错误设置为手机号，而非文档
• 请求参数格式细节问题：如大小写、字段嵌套错误（虽然表面看请求结构正确）

解决方案 #

1. 验证模板实际配置
   登录Meta Business Manager，找到该模板并查看HEADER组件的参数类型，确认是否为「文档」而非「手机号」。若配置错误，重新修改并提交审核。

2. 等待缓存同步
   删除模板后，等待15-30分钟再重建模板。Meta的模板系统存在缓存机制，刚操作的模板可能需要时间同步到API服务器。

3. 调整请求参数大小写
   将请求中HEADER相关的字段改为大写，匹配模板返回的格式：

   {
       "type": "HEADER",
       "parameters": [
           {
               "type": "DOCUMENT",
               "document": {
                   "link": "https://eppg.fgv.br/sites/default/files/teste.pdf",
                   "filename": "teste.pdf"
               }
           }
       ]
   }
   

4. 检查文档链接有效性
   确保提供的文档链接是公开可访问的，无身份验证或地域限制，WhatsApp服务器需要能正常抓取该文档。

5. 重新提交模板审核
   若上述方法无效，删除现有模板，重新创建并严格按照DOCUMENT类型配置HEADER，提交审核通过后再尝试发送。

内容的提问来源于stack exchange，提问作者Lucas Messias