Gupshup发送带附件模板消息返回1005错误的传参咨询

错误码1005的核心触发逻辑是：接收用户不在24小时消息会话窗口内时，请求内容未被识别为已通过审核的HSM模板，你之前测试的4种参数结构均不符合带附件HSM模板的传参规范，正确实现方式如下：

前置校验项 #

• 外层API请求必填参数不能缺失：apikey为账号对应接口密钥、destination为接收方手机号（带国家码，不带+前缀）、source为Gupshup后台绑定的WhatsApp商业号码、channel固定传值whatsapp
• 确认已审核通过的模板名称、语言代码、支持的附件类型和后台配置完全一致，大小写、空格不能有偏差
• 附件公网URL必须满足：HTTPS协议、无鉴权/防盗链限制、无重定向、MIME类型和模板要求匹配、文件大小符合WhatsApp限制（文档类最大100MB）

正确的message字段JSON结构 #

你之前直接将type设为file的写法是24小时活跃窗口内的会话消息格式，不属于HSM模板消息格式，非活跃窗口下发送必然触发模板匹配失败。带附件的HSM模板需要将type固定为template，媒体参数嵌套在hsm字段下，参考结构如下：

{
  "isHSM": "true",
  "type": "template",
  "hsm": {
    "templateName": "后台已审核模板的精确名称",
    "language": {
      "policy": "deterministic",
      "code": "模板对应语言代码，如zh_CN、en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "document",
            "document": {
              "link": "附件公网直连URL",
              "filename": "附件展示文件名，需带正确后缀如report.pdf"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          // 按模板正文占位符顺序传对应参数，无占位符则传空数组
        ]
      }
    ]
  }
}

常见踩坑点 #

• 不要在请求中直接通过text/caption字段传完整模板正文：HSM模板正文已在Gupshup后台留存审核，请求时仅需传占位符对应的参数，自行传入全文会导致内容和后台模板不匹配
• isHSM字段值必须是字符串类型的"true"，不能传布尔值true
• 若模板配置的是图片/视频类附件，将header下参数的type对应改为image/video，嵌套字段对应改为image.link/video.link即可

内容的提问来源于stack exchange，提问作者Simon Hughes