# WhatsApp 身份验证模板

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

## 发送前须知

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

发送 Bird 内置目录模板 `bird_otp` 和 `bird_otp_authifly` 不需要你完成任何验证。这些模板存放在 Bird 自有的 WhatsApp Business Accounts 上，托管发送路径不会检查你的商业验证状态。

当关联的商业账户报告 `not_verified` 时，Bird 会拒绝身份验证模板的创建或复制，返回 `412` [`E15043`](/docs/api/errors/E15043) `WhatsAppTemplateBusinessNotVerified`。请检查关联账户及其最新的同步状态。有关验证流程和状态处理，请参阅 [WhatsApp 商业验证](/docs/knowledge-base/whatsapp/business-verification)。

实用工具类和营销类模板的创建不受此门槛影响；无论你的验证状态如何，都可以继续创建和编辑这些模板。

在仪表板中、通过 [`bird` CLI](/docs/cli) 或通过 [MCP server](/docs/ai/mcp-server) 创建模板。参阅[创建 WhatsApp 模板](/docs/guides/whatsapp/authoring-templates)了解完整流程。

## 发送验证码

使用 `POST /v1/whatsapp/messages` 并传入一个指定目录 slug 的 `template` 对象：

**TypeScript**

```typescript
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);
```

Examples: [TypeScript](/zh-sg/wendang/guides/whatsapp/templates/authentication.ts.md) · [Python](/zh-sg/wendang/guides/whatsapp/templates/authentication.py.md) · [Go](/zh-sg/wendang/guides/whatsapp/templates/authentication.go.md) · [PHP](/zh-sg/wendang/guides/whatsapp/templates/authentication.php.md) · [CLI](/zh-sg/wendang/guides/whatsapp/templates/authentication.cli.md) · [MCP](/zh-sg/wendang/guides/whatsapp/templates/authentication.mcp.md) · [cURL](/zh-sg/wendang/guides/whatsapp/templates/authentication.curl.md)

此类别有四条特定规则：

- **省略 `from`。** Bird 托管的模板会根据类别和地区自行选择发送者，因此设置 `from` 会返回 `422` [`E15018`](/docs/api/errors/E15018) `WhatsAppSenderNotAllowed`。这与自由格式发送相反，后者要求提供 `from`，如果你从交互消息页面来到这里，值得留意这一点。
- **`to` 必须是 E.164 格式的电话号码。** 身份验证模板不能发送到商业范围的用户 ID；否则会返回 `422` [`E15014`](/docs/api/errors/E15014) `WhatsAppRecipientNotSupportedForTemplate`。
- **正文只接受一个位置参数，即验证码。** 零个参数或使用命名参数会返回 `422` [`E15003`](/docs/api/errors/E15003) `WhatsAppTemplateParameterMismatch`。身份验证是 Meta 唯一使用位置参数的类别；其他所有类别都使用命名参数。
- **不需要客服会话窗口。** 模板发送不受会话窗口限制，这正是验证码模板存在的原因：它必须能触达从未给你发过消息的人。

从模板目录中读取 `bird_otp` 或 `bird_otp_authifly` 的可用语言。如果请求的语言不可用，发送会失败，而不会替换为其他语言。

## 复制验证码按钮

Meta 自行编写身份验证模板的正文，作为一个包含单个验证码占位符的预设内容，因此你提供标志位而非文本。按钮组件在发送中是可选的：如果你不包含按钮，Bird 会自动为你添加，使用与正文相同的验证码。你也可以自行提供：

```json
{ "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 投递消息的方式，仅将消息发送到收件人的主设备。参阅[模板指南](/docs/knowledge-base/whatsapp/template-guidelines)了解完整的固定结构、字符限制和审核流程。

## 费用

类别和目的地决定价格。有关发送到主要所在地以外国家/地区时价格的变化，请参阅 [WhatsApp 身份验证国际费率](/docs/knowledge-base/whatsapp/authentication-international-rates)；有关发送何时计费，请参阅[费用与计费](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing)。具体费率请查看 [WhatsApp 定价](/products/whatsapp/pricing)。

## 注意事项

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

## 后续步骤

- [WhatsApp 模板](/docs/guides/whatsapp/templates)：浏览目录以及通用的按模板发送约定
- [实用工具模板](/docs/guides/whatsapp/templates/utility)：订单更新、预约提醒和账户通知
- [WhatsApp 商业验证](/docs/knowledge-base/whatsapp/business-verification)：验证流程及其解锁的其他功能

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)