WhatsApp 身份验证模板
身份验证模板用于发送一次性验证码。创建模板时,Meta 会提供其文案。发送时,将验证码作为 body 参数传入。
发送前须知
选择使用 Bird 托管的模板,还是在自己的商业账户上创建模板。
发送 Bird 内置目录模板 bird_otp 和 bird_otp_authifly 不需要你完成任何验证。这些模板存放在 Bird 自有的 WhatsApp Business Accounts 上,托管发送路径不会检查你的商业验证状态。
当关联的商业账户报告 not_verified 时,Bird 会拒绝身份验证模板的创建或复制,返回 412 E15043 WhatsAppTemplateBusinessNotVerified。请检查关联账户及其最新的同步状态。有关验证流程和状态处理,请参阅 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);msg = client.whatsapp.send(
to="+14155550100",
template="bird_otp",
language="en",
components=[{"type": "body", "parameters": [{"type": "text", "text": "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)
}
code := "481920"
components := []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &code}},
}}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+14155550100",
Template: "bird_otp",
Language: "en",
Components: components,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$components = [
(new WhatsAppMessageTemplateComponent())
->setType('body')
->setParameters([
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setText('481920'),
]),
];
$message = $bird->whatsapp->send(
to: '+14155550100',
template: 'bird_otp',
language: 'en',
components: $components,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--components '[{"parameters":[{"text":"481920","type":"text"}],"type":"body"}]' \
--language en \
--template bird_otp \
--to +14155550100{
"name": "whatsapp_send",
"arguments": {
"template": {
"components": [
{
"parameters": [
{
"text": "481920",
"type": "text"
}
],
"type": "body"
}
],
"language": "en",
"slug": "bird_otp"
},
"to": "+14155550100"
}
}curl -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",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "481920"
}
]
}
]
}
}'此类别有四条特定规则:
- 省略 from。 Bird 托管的模板会根据类别和地区自行选择发送者,因此设置 from 会返回 422 E15018 WhatsAppSenderNotAllowed。这与自由格式发送相反,后者要求提供 from,如果你从交互消息页面来到这里,值得留意这一点。
- to 必须是 E.164 格式的电话号码。 身份验证模板不能发送到商业范围的用户 ID;否则会返回 422 E15014 WhatsAppRecipientNotSupportedForTemplate。
- 正文只接受一个位置参数,即验证码。 零个参数或使用命名参数会返回 422 E15003 WhatsAppTemplateParameterMismatch。身份验证是 Meta 唯一使用位置参数的类别;其他所有类别都使用命名参数。
- 不需要客服会话窗口。 模板发送不受会话窗口限制,这正是验证码模板存在的原因:它必须能触达从未给你发过消息的人。
从模板目录中读取 bird_otp 或 bird_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 投递消息的方式,仅将消息发送到收件人的主设备。参阅模板指南了解完整的固定结构、字符限制和审核流程。
费用
注意事项
- Bird 的内置模板无法投递到九个国家。 bird_otp 和 bird_otp_authifly 从 Bird 自有的 WhatsApp Business Accounts 发送,这些账户不会将身份验证消息投递到埃及、印度、印度尼西亚、马来西亚、尼日利亚、巴基斯坦、沙特阿拉伯、南非或阿拉伯联合酋长国。此类发送会在产生任何费用之前被拒绝,返回 422 E15063 WhatsAppDestinationRestricted。你在自己账户上创建的模板,从你自己的号码发送,可以正常到达这些国家。Verify 也可以到达这些国家,它会自动将验证码切换到其他渠道。
- 自创模板发送需要 from,且该号码必须位于与模板相同的 WhatsApp Business Account 上。 来自不同账户的发送者会在产生任何费用之前被拒绝,返回 422 E15023 WhatsAppSenderWABAMismatch。
- 只有版本已批准且处于生效状态的语言才能发送。 草稿、待审核、被拒绝或已暂停的语言不可发送。
- Meta 可以主动重新分类模板。 无法退出此机制,重新分类会同时变更跟随该类别的定价和投递规则。
- 模板的类别与其语言的类别可能不一致。 参阅 WhatsApp 模板了解发送路径如何解决此问题。
- 已导入的身份验证模板无法被复制。 Bird 无法将 WhatsApp 生成的文案反向读取为构建新模板所需的设置;这会返回 422 E15024 WhatsAppTemplateContentNotDuplicable。请改为创建一个新模板,设置自己的安全建议和验证码过期时间。
后续步骤
- WhatsApp 模板:浏览目录以及通用的按模板发送约定
- 实用工具模板:订单更新、预约提醒和账户通知
- WhatsApp 商业验证:验证流程及其解锁的其他功能