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);msg = client.whatsapp.send(
to="+14155550100",
template="bird_otp",
language="en",
parameters={"code": "481920"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+14155550100",
Template: "bird_otp",
Language: "en",
Parameters: map[string]any{"code": "481920"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$message = $bird->whatsapp->send(
to: '+14155550100',
template: 'bird_otp',
language: 'en',
parameters: ['code' => '481920'],
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--language en \
--parameters '{"code":"481920"}' \
--template bird_otp \
--to +14155550100curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550100",
"template": {
"slug": "bird_otp",
"language": "en",
"parameters": {
"code": "481920"
}
}
}'此类别有四条特定规则:
- 省略
from。 Bird 托管的模板会根据类别和地区自行选择发送方,因此设置from会返回422E15018WhatsAppSenderNotAllowed。这与自由格式发送相反,后者要求提供from。如果你是从交互式消息页面转来的,请注意这一区别。 to必须是 E.164 格式的电话号码。 身份验证模板不能发送给企业范围的用户 ID,否则会返回422E15014WhatsAppRecipientNotSupportedForTemplate。- 验证码放在
parameters.code中。 它会填入正文的占位符和复制验证码按钮。components发送则只接受一个按位置传递的正文参数,即验证码。不提供参数或为参数命名,都会返回422E15003WhatsAppTemplateParameterMismatch。 - 无需客户服务窗口。 模板发送不受窗口限制,这正是验证码模板存在的原因:它必须能送达从未给你发过消息的人。
从模板目录中读取 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 发送,而这些账户不向埃及、印度、印度尼西亚、马来西亚、尼日利亚、巴基斯坦、沙特阿拉伯、南非和阿拉伯联合酋长国传送身份验证消息。此类发送会在产生任何费用之前被拒绝,返回422E15063WhatsAppDestinationRestricted。在您自己的账户上创建并从您自己的号码发送的模板,可以正常送达这些国家。Verify 也能送达这些国家,它会自动将验证码改由其他渠道发送。 - 发送自建模板时必须提供
from,且它必须与模板位于同一个 WhatsApp Business Account 下。 来自其他账户的发送方会在产生任何费用之前被拒绝,返回422E15023WhatsAppSenderWABAMismatch。 - 只有版本已获批准并已上线的语言才能发送。 处于草稿、待审核、已拒绝或已暂停状态的语言无法发送。
- Meta 可以自行重新归类模板。 您无法选择退出,重新归类后,随类别而定的定价和投递规则也会随之改变。
- 模板的类别与其语言的类别可能不一致。 发送流程如何处理这种情况,请参阅 WhatsApp 模板。
- 导入的身份验证模板无法复制。 Bird 无法将 WhatsApp 生成的文案读回为创建新模板所需的设置,因此会返回
422E15024WhatsAppTemplateContentNotDuplicable。请改为新建一个模板,并为其设置安全建议和验证码有效期。
后续步骤
- WhatsApp 模板:浏览模板目录及通用的按模板发送约定
- 实用工具模板:订单更新、预约提醒和账户通知
- WhatsApp 企业验证:验证的工作方式,以及验证还能解锁哪些功能