Sign inGet started

WhatsApp 身份验证模板

身份验证模板用于发送一次性验证码。创建模板时,Meta 会提供其文案。发送时,将验证码作为 body 参数传入。

发送前须知

选择使用 Bird 托管的模板,还是在自己的商业账户上创建模板。
发送 Bird 内置目录模板 bird_otpbird_otp_authifly 不需要你完成任何验证。这些模板存放在 Bird 自有的 WhatsApp Business Accounts 上,托管发送路径不会检查你的商业验证状态。
当关联的商业账户报告 not_verified 时,Bird 会拒绝身份验证模板的创建或复制,返回 412 E15043 WhatsAppTemplateBusinessNotVerified。请检查关联账户及其最新的同步状态。有关验证流程和状态处理,请参阅 WhatsApp 商业验证
实用工具类和营销类模板的创建不受此门槛影响;无论你的验证状态如何,都可以继续创建和编辑这些模板。
在仪表板中、通过 bird CLI 或通过 MCP server 创建模板。参阅创建 WhatsApp 模板了解完整流程。

发送验证码

使用 POST /v1/whatsapp/messages 并传入一个指定目录 slug 的 template 对象:
const msg = await bird.whatsapp.send({
  to: "+14155550100",
  template: {
    slug: "bird_otp",
    language: "en",
    components: [{ type: "body", parameters: [{ type: "text", text: "481920" }] }],
  },
});
console.log(msg.id, msg.status);
此类别有四条特定规则:
  • 省略 from Bird 托管的模板会根据类别和地区自行选择发送者,因此设置 from 会返回 422 E15018 WhatsAppSenderNotAllowed。这与自由格式发送相反,后者要求提供 from,如果你从交互消息页面来到这里,值得留意这一点。
  • to 必须是 E.164 格式的电话号码。 身份验证模板不能发送到商业范围的用户 ID;否则会返回 422 E15014 WhatsAppRecipientNotSupportedForTemplate
  • 正文只接受一个位置参数,即验证码。 零个参数或使用命名参数会返回 422 E15003 WhatsAppTemplateParameterMismatch。身份验证是 Meta 唯一使用位置参数的类别;其他所有类别都使用命名参数。
  • 不需要客服会话窗口。 模板发送不受会话窗口限制,这正是验证码模板存在的原因:它必须能触达从未给你发过消息的人。
从模板目录中读取 bird_otpbird_otp_authifly 的可用语言。如果请求的语言不可用,发送会失败,而不会替换为其他语言。

复制验证码按钮

Meta 自行编写身份验证模板的正文,作为一个包含单个验证码占位符的预设内容,因此你提供标志位而非文本。按钮组件在发送中是可选的:如果你不包含按钮,Bird 会自动为你添加,使用与正文相同的验证码。你也可以自行提供:
代码示例
{ "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }
无论哪种方式,最终到达 WhatsApp 的只有一个按钮,即复制验证码按钮:点击后将验证码复制到剪贴板。Bird 仅支持 copy_code;Meta 为身份验证模板记录的另外两种按钮行为(一键点击和零点击自动填充)目前在 Bird 上不可用。
创建模板的按钮遵循相同结构:一个 otp 按钮,且模板不接受其他按钮类型。你提供 add_security_recommendation(一个布尔值,显示在正文中)和 code_expiration_minutes(1 到 90,显示在页脚中)来代替编写文案。

Meta 在身份验证模板中允许的内容

Meta 固定了身份验证模板的结构并审核其内容:模板中不允许 URL、媒体或表情符号,且验证码参数上限为 15 个字符。该类别还会改变 WhatsApp 投递消息的方式,仅将消息发送到收件人的主设备。参阅模板指南了解完整的固定结构、字符限制和审核流程。

费用

类别和目的地决定价格。有关发送到主要所在地以外国家/地区时价格的变化,请参阅 WhatsApp 身份验证国际费率;有关发送何时计费,请参阅费用与计费。具体费率请查看 WhatsApp 定价

注意事项

  • Bird 的内置模板无法投递到九个国家。 bird_otpbird_otp_authifly 从 Bird 自有的 WhatsApp Business Accounts 发送,这些账户不会将身份验证消息投递到埃及、印度、印度尼西亚、马来西亚、尼日利亚、巴基斯坦、沙特阿拉伯、南非或阿拉伯联合酋长国。此类发送会在产生任何费用之前被拒绝,返回 422 E15063 WhatsAppDestinationRestricted。你在自己账户上创建的模板,从你自己的号码发送,可以正常到达这些国家。Verify 也可以到达这些国家,它会自动将验证码切换到其他渠道。
  • 自创模板发送需要 from,且该号码必须位于与模板相同的 WhatsApp Business Account 上。 来自不同账户的发送者会在产生任何费用之前被拒绝,返回 422 E15023 WhatsAppSenderWABAMismatch
  • 只有版本已批准且处于生效状态的语言才能发送。 草稿、待审核、被拒绝或已暂停的语言不可发送。
  • Meta 可以主动重新分类模板。 无法退出此机制,重新分类会同时变更跟随该类别的定价和投递规则。
  • 模板的类别与其语言的类别可能不一致。 参阅 WhatsApp 模板了解发送路径如何解决此问题。
  • 已导入的身份验证模板无法被复制。 Bird 无法将 WhatsApp 生成的文案反向读取为构建新模板所需的设置;这会返回 422 E15024 WhatsAppTemplateContentNotDuplicable。请改为创建一个新模板,设置自己的安全建议和验证码过期时间。

后续步骤