为何无法通过Twilio以编程方式发送模板化WhatsApp消息？

问题背景 #

使用以下代码发送WhatsApp消息，内容匹配Twilio控制台的“sample_issue_resolution”模板，可成功发送给已订阅Twilio WhatsApp沙盒的号码，但发送给未订阅沙盒的号码时，无代码报错但对方收不到消息，使用已审核的自定义模板也存在相同问题。

代码示例 #

const client = require('twilio')(accountSid, authToken);
const issueResolution = 'Hi Malcolm, were we able to solve the issue that you were facing?';

client.messages
      .create({
         from: senderNumber, 
         body: issueResolution,
         to: receiverNumber,
       })
      .then(message => {
        console.log(JSON.stringify(message , null, 2));
      });

问题原因 #

• WhatsApp商业消息合规限制：未订阅沙盒的号码属于正式收件人，WhatsApp规则要求发送给这类用户的消息必须使用已通过审核的官方模板，且必须通过Twilio指定模板的方式发送，不能直接写消息内容。沙盒环境是测试用的，允许自由发送消息，但正式环境受严格合规约束。
• 模板调用方式错误：当前代码直接通过body字段发送内容，即使内容匹配模板，Twilio也不会识别为模板消息，而是按普通消息处理。普通消息仅能发送给已主动发起对话（比如给你的Twilio号码发过消息、订阅沙盒）的用户，未主动对话的用户无法接收。
• 模板状态或格式不符：自定义模板可能未真正通过审核，或代码中使用的内容与审核通过的模板存在细微差异（比如标点、变量位置），导致Twilio拒绝按模板消息投递。
• 账户或号码配置问题：Twilio账户未完成WhatsApp商业账号的验证流程，或发送号码未绑定到合规的业务配置，导致正式消息无法投递。

调试方法 #

• 修正模板调用方式：改用Twilio的模板调用规范，通过contentSid（或templateId）指定模板，变量通过contentVariables传递。示例代码：

const client = require('twilio')(accountSid, authToken);

client.messages
  .create({
     from: senderNumber, 
     contentSid: 'YOUR_TEMPLATE_CONTENT_SID', // 从Twilio控制台模板页面获取
     to: receiverNumber,
     contentVariables: JSON.stringify({
       "1": "Malcolm" // 对应模板中的变量占位符，按模板定义的顺序填写
     })
   })
  .then(message => console.log(JSON.stringify(message, null, 2)))
  .catch(err => console.error(err));

• 查看Twilio消息日志：在Twilio控制台的消息记录中找到对应的消息条目，查看其状态和错误详情。若状态为undelivered，会附带错误码（比如63003表示模板问题），可直接定位原因。
• 验证模板状态：确认自定义模板在Twilio控制台中显示“已审核”状态，且模板内容（包括变量占位符）与你要发送的完全一致，无任何修改。
• 检查账户合规性：确认你的Twilio账户已完成WhatsApp商业注册流程，包括业务信息验证、发送号码的绑定与审核。
• 做对比测试：找一个已主动给你的Twilio号码发送过WhatsApp消息的非沙盒号码，用原有代码发送普通消息，若能收到则说明问题出在模板调用方式而非账户或号码本身。

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