如何在 WhatsApp Business API 模板消息中正确添加图片变量-php教程-PHP中文网

如何在 WhatsApp Business API 模板消息中正确添加图片变量

whatsapp business api 不支持直接在模板参数中使用外部图片 url；必须先上传图片获取媒体 id，再通过 type: "image" 参数引用该 id，否则会触发参数错误或媒体验证失败。

whatsapp business api 不支持直接在模板参数中使用外部图片 url；必须先上传图片获取媒体 id，再通过 type: "image" 参数引用该 id，否则会触发参数错误或媒体验证失败。

在 WhatsApp Business Platform（基于 Meta Graph API）中，向模板消息（Template Message）插入图片并非简单填写一个 URL 即可完成。你遇到的错误 "(#100) The parameter messaging_product is required" 虽表面指向缺失 messaging_product 字段，但其根本原因往往隐藏在更底层的请求结构问题中——而你代码中真正违反 API 规范的关键点在于：试图在 parameters 数组中直接使用 "type": "image" 并传入 link 字段，这是不被支持的用法。

✅ 正确流程如下（三步不可省略）：

上传图片获取媒体 ID
必须先调用 /media 端点上传图片文件（支持 JPG、PNG、WEBP 等），返回包含 id 和临时 url 的媒体对象。注意：上传需使用 POST /{phone_number_id}/media，并携带 file（二进制）或 link（需为公网可访问且 HTTPS）参数，同时设置 messaging_product=whatsapp —— 这正是报错提示所要求的字段。

示例（cURL）：
```
curl -X POST \
  "https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/media" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -F "file=@/path/to/image.png" \
  -F "messaging_product=whatsapp" \
  -F "type=image/png"
```
成功响应：

WhatsApp 428 修复
修复 WhatsApp Web 的 428 错误及代理配置问题，适用于连接断开（状态428）、需要配置代理或在新机器部署 OpenClaw 后出现的 WhatsApp 连接故障。

下载
```
{
  "id": "1234567890123456789"
}
```

在模板参数中引用媒体 ID（非 URL）
上传成功后，将返回的 id 作为 image.id 值传入模板参数，不是 image.link。你的原始 JSON 中误用了 "link" 字段，应改为 "id"：

{
  "to": "xxxxx",
  "recipient_type": "individual",
  "messaging_product": "whatsapp",
  "type": "template",
  "template": {
    "namespace": "88b39973_f0d5_54e1_29cf_e80f1e3da4f2",
    "name": "noticia",
    "language": { "code": "es" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Richard" },
          { 
            "type": "image", 
            "image": { "id": "1234567890123456789" } 
          }
        ]
      }
    ]
  }
}

⚠️ 注意事项：

messaging_product=whatsapp 是所有 WhatsApp 消息请求的必需顶层参数（非仅上传时需要）；
图片模板变量必须定义在模板的 header 组件中（而非 body），这是关键限制！你当前将 type: "image" 放在 body.parameters 内是无效的 —— WhatsApp 模板规范要求图片仅能作为消息头部（header）展示。

✅ 正确组件结构示例：

"components": [
  {
    "type": "header",
    "parameters": [
      {
        "type": "image",
        "image": { "id": "1234567890123456789" }
      }
    ]
  },
  {
    "type": "body",
    "parameters": [
      { "type": "text", "text": "Richard" },
      { "type": "text", "text": "https://intranet.example.com/noticia" }
    ]
  }
]

确保模板已审核并启用图片变量
在 WhatsApp Manager 中创建模板时，需显式选择“Image”类型占位符（如 {{1}} 设为 Image 类型），且模板状态为 APPROVED。纯文本变量无法替换为图片。

? 总结：

❌ 错误：在 body.parameters 中使用 image.link；遗漏 messaging_product；未上传图片直接引用 URL。
✅ 正确：先上传 → 获取 media.id → 在 header.parameters 中用 "image": {"id": "..."} → 全局请求头含 messaging_product=whatsapp。
推荐使用官方 SDK（如 Python 的 facebook-business 或 Ruby 的 ruby_whatsapp_sdk）封装上传与发送逻辑，避免手动构造 multipart 请求出错。