使用Postman调用WhatsApp API发送模板消息时出现格式不匹配错误

核心问题分析 #

错误提示header: Format mismatch, expected DOCUMENT, received UNKNOWN说明API无法识别传入的header文档参数，大概率是请求结构错误或模板配置不匹配导致的。

分步解决方案 #

1. 修正API请求的参数结构 #

你的请求中components字段被放在了template对象外部，不符合WhatsApp API规范。正确结构需将components嵌套在template对象内部：

{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "{{Recipient-Phone-Number}}",
    "type": "template",
    "template": {
        "name": "test_temp",
        "language": {
            "code": "en_US"
        },
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "document",
                        "document": {
                            "filename": "Purchase Note - 123456789.pdf",
                            "link": "https://www.adobe.com/support/products/enterprise/knowledgecenter/media/c4611_sample_explain.pdf"
                        }
                    }
                ]
            },
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "123456789"
                    }
                ]
            }
        ]
    }
}

2. 验证模板的Header参数类型 #

登录Meta Business Manager，进入WhatsApp模板管理页面，找到test_temp模板：

• 确认模板的Header组件类型设置为Document（而非Text、Image等）
• 确保模板已通过Meta审核（未审核或审核不通过的模板无法正常调用）

3. 检查文档参数的有效性 #

• 若使用link：确保链接为公共可访问的HTTPS地址，无登录/权限验证要求，且文件类型为WhatsApp支持的文档格式（如PDF）
• 若使用media_id：必须是通过WhatsApp Media API上传成功后返回的有效ID，且上传时文件类型为document（不能是image/video等其他类型）

4. 检查字段拼写与格式一致性 #

• 确认所有字段名拼写正确（如document、filename、link等）
• 确保language.code与模板创建时选择的语言完全一致（示例中模板用en_US，请求也必须匹配）

内容的提问来源于stack exchange，提问作者Teljo Antony