使用Qontak API发送WhatsApp CTA按钮模板时遭遇格式不匹配错误（#132012）的求助

阿华AIGC实验室

2026-4-13

Qontak API发送WhatsApp CTA按钮模板时遭遇格式不匹配错误（#132012）的求助

看起来你遇到的问题根源在于模板要求的IMAGE类型Header没有在API请求中正确填充——虽然调用接口返回了201状态码，但WhatsApp端的参数校验发现缺少Header配置，因此触发了#132012格式不匹配错误。

问题分析

你的模板明确配置了header.format: "IMAGE"，这意味着发送模板消息时，必须在请求参数中提供对应的图片内容；而你当前的请求parameters里只包含了buttons和body，完全遗漏了Header相关的参数，导致WhatsApp端识别为UNKNOWN类型，触发校验失败。

你需要在请求的parameters对象中添加header字段，传入符合要求的图片参数。以下是修改后的代码示例：

async function sendCtaUrlMessage() {
  try {
    const withCtaURL = {
      "to_name": "{{Customer-Name}}",
      "to_number": "{{Phone-Number}}",
      "message_template_id": "{{Template-ID}}",
      "channel_integration_id": "{{Channel-Integration-ID}}",
      "language": {
          "code": "id"
      },
      "parameters": {
          // 新增Header参数，匹配模板的IMAGE格式要求
          "header": [
            {
              "type": "IMAGE",
              "value": "https://your-public-image-url.com/valid-image.jpg" // 替换为实际可访问的图片URL
            }
          ],
          "buttons": [
            {
              "index": "0",
              "type": "URL",
              "value": "{{CTA-URL}}"
            }
          ],
          "body": []
      }
    }
    const response = await api.broadcast.createBroadcastDirect(withCtaURL)
    console.log("Response:", response);
  } catch (error) {
    console.error("Error:", error.response.data);
  }
}

sendCtaUrlMessage()

额外注意事项

确保图片URL有效：提供的图片链接必须是公开可访问的（无需登录/权限验证），格式为JPG/PNG，且大小符合WhatsApp的媒体规范（建议不超过5MB）。
匹配模板参数类型：Header的type必须严格和模板的header.format一致（这里是IMAGE），不能传其他类型。
验证媒体兼容性：如果直接传外部URL遇到问题，可以先通过Qontak的媒体上传接口将图片上传到平台，获取媒体ID后再传入value字段。

备注：内容来源于stack exchange，提问作者udn