通过WhatsApp API发送视频标题时出现格式不匹配错误

我在测试通过WhatsApp API发送带视频标题的模板消息时，持续收到以下错误：

{
    "error": {
        "message": "(#132012) Parameter format does not match format in the created template",
        "type": "OAuthException",
        "code": 132012,
        "error_data": {
            "messaging_product": "whatsapp",
            "details": "header: Format mismatch, expected VIDEO, received UNKNOWN"
        },
        "fbtrace_id": "AVPT6EiX3RemyP3uv4S36FZ"
    }
}

我尝试过使用可公开访问的视频URL，甚至直接复用模板里的示例链接，都出现同样的错误。我了解用于上传媒体的Resumable API，但本次测试不需要使用该功能，急需解决办法。

已通过审核的模板详情 #

{
    "name": "vid_test",
    "previous_category": "UTILITY",
    "components": [
        {
            "type": "HEADER",
            "format": "VIDEO",
            "example": {
                "header_handle": [
                    "https://scontent.whatsapp.net/v/t61.29466-34/380066992_950204086818012_8956032979900394560_n.mp4?ccb=1-7&_nc_sid=8b1bef&_nc_ohc=pmivIdgTvrAQ7kNvgEgxK28&_nc_oc=Adg2vVNVfN1TlUWzFmJxHpa830uVJRRCSKsooFiDp0E_AQ7gLbB-RIGSlx8UNvM0cXw&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&oh=01_Q5AaIFBxPaJzBmN9IaDMHWuIw-w8fQX3uHngw2A_qNyhKBVw&oe=666BB20F"
                ]
            }
        },
        {
            "type": "BODY",
            "text": "tesing {{1}} and use code {{2}} to get amazing discounts on testing videos.",
            "example": {
                "body_text": [
                    [
                        "Message content",
                        "MSG25"
                    ]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "Use the buttons below to manage your marketing subscriptions"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "QUICK_REPLY",
                    "text": "Unsubscribe from Promos"
                },
                {
                    "type": "QUICK_REPLY",
                    "text": "Unsubscribe from All"
                }
            ]
        }
    ],
    "language": "en",
    "status": "APPROVED",
    "category": "MARKETING",
    "id": "950180443487043"
}

发送请求的POST体 #

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "MY PHONE NUMBER",
  "type": "template",
  "template": {
    "name": "vid_test",
    "language": {
      "code": "en"
    }
  },
  "components": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "VIDEO",
          "video": {
            "Link": "https://static.vecteezy.com/system/resources/previews/006/996/488/mp4/timelapse-full-sunset-free-video.mp4"
          }
        }
      ]
    },
    {
      "Type": "Body",
      "parameters": [
        {
          "type": "text",
          "text": "Var 1"
        },
        {
          "type": "text",
          "text": "Var 2"
        }
      ]
    }
  ]
}

问题根源与修复方案 #

• 字段大小写错误：WhatsApp API的字段名严格区分大小写，请求体存在两处格式错误：
  1. 视频参数中的Link需改为小写的link；
  2. Body组件的Type需改为小写的type，同时组件类型值Body也要改为小写的body，与模板定义保持一致。
• 视频URL验证：确保视频URL满足以下要求：
  • 直接指向MP4文件，而非网页跳转链接；
  • 视频编码为H.264/AAC，文件大小不超过16MB；
  • 服务器返回的HTTP响应头包含正确的Content-Type: video/mp4，避免API无法识别媒体类型。

修改后的请求体示例 #

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "MY PHONE NUMBER",
  "type": "template",
  "template": {
    "name": "vid_test",
    "language": {
      "code": "en"
    }
  },
  "components": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "VIDEO",
          "video": {
            "link": "https://static.vecteezy.com/system/resources/previews/006/996/488/mp4/timelapse-full-sunset-free-video.mp4"
          }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Var 1"
        },
        {
          "type": "text",
          "text": "Var 2"
        }
      ]
    }
  ]
}

内容的提问来源于stack exchange，提问作者Suman Roy