迁移至Twilio Content Builder API遇21656错误：变量值含撇号无效

问题背景 #

迁移至Twilio Content Builder API发送模板消息时，遇到错误21656（“ContentVariables参数无效”），仅当内容变量值包含撇号（如people's）时触发。

相关代码 #

async sendWhatsappViaContentId({ from, to, contentId, jsonData, additionalSettings = {} }) {
  return this.client.messages.create({
    from: `whatsapp:${from}`,
    to: `whatsapp:${to}`,
    contentSid: contentId,
    contentVariables: JSON.stringify(jsonData),
    statusCallback: additionalSettings?.ignoreCallback ? this.ignoreStatusCallbackUrl : this.statusCallbackUrl,
    ...(additionalSettings.customCallback && { statusCallback: additionalSettings.customCallback }),
  });
}

触发错误的示例数据 #

{
  "1": "aaasdasd",
  "2": "people's"
}

疑问 #

1. 如何正确处理内容变量值中的撇号？
2. 还有哪些特殊字符可能引发该错误？
3. 使用Content Builder API时，是否有推荐的转义或编码方式？

解决方案 #

1. 撇号的处理方式 #

Twilio的Content Variables参数要求传入的JSON字符串中，单引号需要进行双重转义。JSON.stringify()处理含撇号的字符串时，只会生成people's这样的结果，但Twilio解析时会把单引号当成JSON结构的一部分，导致格式错误。

修改方式：在JSON.stringify()之后，把所有单引号替换为\\'（双层转义，确保最终传到Twilio的参数里是\'）。

修改后的代码片段：

contentVariables: JSON.stringify(jsonData).replace(/'/g, "\\'"),

处理后people's会变成people\'s，符合Twilio的解析要求。

2. 可能引发错误的其他特殊字符 #

除单引号外，以下字符也可能触发参数无效错误：

• 未转义的双引号：手动拼接JSON时容易出错，JSON.stringify()会自动转义为\"，通常无需额外处理
• 反斜杠：本身需要转义，否则会破坏JSON结构
• 换行符、制表符等空白控制字符：JSON.stringify()会自动转义，但手动处理时遗漏转义会出问题

3. 推荐的转义/编码方式 #

• 优先用JSON.stringify()处理基础转义：它会自动处理双引号、反斜杠、控制字符等标准JSON转义需求
• 针对Twilio特殊要求补充处理：仅单引号需要额外替换，因为Twilio对Content Variables的JSON解析有特殊的单引号处理逻辑
• 避免手动拼接JSON字符串：手动拼接容易出现转义遗漏，始终用JSON.stringify()生成基础JSON，再针对单引号做替换

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