Sign inGet Started

WhatsApp 身份验证模板

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

发送之前

选择使用 Bird 托管的模板,还是在您自己的企业账户上创建模板。

发送 Bird 预置的目录模板 bird_otp 和 bird_otp_authifly 时,无需完成您自己的验证。这些模板位于 Bird 自有的 WhatsApp Business Account 上,托管发送路径从不检查您企业的验证状态。

当所连接的企业账户报告 not_verified 时,Bird 会拒绝创建或复制身份验证模板,并返回 412 E15043 WhatsAppTemplateBusinessNotVerified。请检查所连接的账户及其最近一次同步的状态。有关验证流程和状态处理,请参阅 WhatsApp 企业验证。

此门槛不影响实用类和营销类模板的创建;无论验证状态如何,您都可以继续创建和编辑这些模板。

您可以在控制台中、使用 bird CLI 或通过 MCP 服务器创建模板。完整流程请参阅创建身份验证模板。

发送验证码

POST /v1/whatsapp/messages,并附带一个指定目录 slug 的 template 对象:

const msg = await bird.whatsapp.send({
  to: "+14155550100",
  template: {
    slug: "bird_otp",
    language: "en",
    parameters: { code: "481920" },
  },
});
console.log(msg.id, msg.status);

此类别有四条特定规则:

  • 省略 from。 Bird 托管的模板会根据类别和地区自行选择发送方,因此设置 from 会返回 422 E15018 WhatsAppSenderNotAllowed。这与自由格式发送相反,后者要求提供 from。如果你是从交互式消息页面转来的,请注意这一区别。
  • to 必须是 E.164 格式的电话号码。 身份验证模板不能发送给企业范围的用户 ID,否则会返回 422 E15014 WhatsAppRecipientNotSupportedForTemplate。
  • 验证码放在 parameters.code 中。 它会填入正文的占位符和复制验证码按钮。components 发送则只接受一个按位置传递的正文参数,即验证码。不提供参数或为参数命名,都会返回 422 E15003 WhatsAppTemplateParameterMismatch。
  • 无需客户服务窗口。 模板发送不受窗口限制,这正是验证码模板存在的原因:它必须能送达从未给你发过消息的人。

从模板目录中读取 bird_otp 或 bird_otp_authifly 支持的语言。如果你请求的语言不可用,发送会失败,而不会改用其他语言。

复制验证码按钮

身份验证模板的正文由 Meta 编写,是带有单个验证码占位符的预设内容,因此你只需提供标志,无需提供文本。parameters 发送会用 code 填充按钮。在 components 发送中,按钮组件是可选的:如果你不提供,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_otp 和 bird_otp_authifly 从 Bird 自己的 WhatsApp Business Account 发送,而这些账户不向埃及、印度、印度尼西亚、马来西亚、尼日利亚、巴基斯坦、沙特阿拉伯、南非和阿拉伯联合酋长国传送身份验证消息。此类发送会在产生任何费用之前被拒绝,返回 422 E15063 WhatsAppDestinationRestricted。在您自己的账户上创建并从您自己的号码发送的模板,可以正常送达这些国家。Verify 也能送达这些国家,它会自动将验证码改由其他渠道发送。
  • 发送自建模板时必须提供 from,且它必须与模板位于同一个 WhatsApp Business Account 下。 来自其他账户的发送方会在产生任何费用之前被拒绝,返回 422 E15023 WhatsAppSenderWABAMismatch。
  • 只有版本已获批准并已上线的语言才能发送。 处于草稿、待审核、已拒绝或已暂停状态的语言无法发送。
  • Meta 可以自行重新归类模板。 您无法选择退出,重新归类后,随类别而定的定价和投递规则也会随之改变。
  • 模板的类别与其语言的类别可能不一致。 发送流程如何处理这种情况,请参阅 WhatsApp 模板。
  • 导入的身份验证模板无法复制。 Bird 无法将 WhatsApp 生成的文案读回为创建新模板所需的设置,因此会返回 422 E15024 WhatsAppTemplateContentNotDuplicable。请改为新建一个模板,并为其设置安全建议和验证码有效期。

后续步骤