如何设置Firebase文档格式，通过MessageBird扩展发送WhatsApp模板消息

Firebase集合中用于MessageBird扩展的消息文档格式，和MessageBird直接API请求格式存在差异，以下是适配扩展要求的、带网站链接按钮的模板消息正确结构：

示例代码（Cloud Functions写入messages集合） #

const admin = require('firebase-admin');
admin.initializeApp();

async function sendTemplateMessage() {
  const messageData = {
    // 必选核心字段
    to: '+1234567890', // 目标用户WhatsApp号码，带完整国家码
    from: '+0987654321', // 你的MessageBird发送号码
    type: 'template',
    channelId: 'whatsapp', // 固定指定渠道为WhatsApp
    template: {
      name: '你的模板名称', // 与MessageBird后台审核通过的模板名完全一致
      language: {
        code: 'en_US', // 模板语言代码，如zh_CN
        policy: 'deterministic' // 固定值，确保匹配指定语言模板
      },
      components: [
        // 替换模板中的文本变量（如果模板有占位符）
        {
          type: 'body',
          parameters: [
            { type: 'text', text: '用户姓名' }
          ]
        },
        // 网站链接按钮配置
        {
          type: 'button',
          sub_type: 'url',
          index: '0', // 按钮索引，从0开始对应模板中第一个按钮
          parameters: [
            {
              type: 'text',
              text: '点击访问官网' // 对应模板中按钮的占位文本
            }
          ]
        }
      ]
    }
  };

  await admin.firestore().collection('messages').add(messageData);
}

关键规则 #

• 结构适配：必须使用template嵌套结构，不能直接用MessageBird API的content字段，这是导致JSON格式错误（code:21）的常见原因。
• 按钮配置：链接按钮的sub_type必须设为url，index要和模板中按钮的位置对应（第一个按钮为0）。
• 必填字段：type: 'template'和channelId: 'whatsapp'是扩展要求的必选字段，不能遗漏。
• 模板一致性：template.name必须和MessageBird后台审核通过的模板名称完全一致，大小写、拼写都不能错。
• 号码格式：to和from号码必须包含完整国际区号，不能省略前缀+。

code:21错误排查 #

出现JSON is not a valid format错误，大概率是以下问题：

• 照搬了MessageBird直接API的字段结构，未适配扩展要求的template嵌套格式。
• components数组结构错误，比如按钮的sub_type未设置、参数类型不匹配。
• 缺少type或channelId等必选字段。

内容的提问来源于stack exchange，提问作者Krishna Shetty