WhatsApp 实用模板
实用模板用于跟进收件人已完成的操作:订单、付款、预约、登录。Bird 的目录中存有八个此类模板,包括 bird_signin_alert 和 bird_delivery_update。请根据模板列表中的分类而非名称来判断一个 slug 的类别:bird_signin_alert 看起来像身份验证模板,但实际上不是,它属于实用类别。
发送前准备
选择一个托管目录模板,或在已关联的商业账户上自行创建一个。
发送 Bird 预置的目录模板无需你进行任何验证,与身份验证类别相同。自行创建实用模板同样不需要验证:与身份验证不同,Meta 的企业验证门槛从不适用于实用类别,因此你可以在未验证的工作区上创建和编辑实用模板。参阅WhatsApp 企业验证了解验证在其他场景下的作用。
to 可以是 E.164 格式的电话号码或业务范围内的用户 ID。实用模板不包含 OTP 按钮,因此不要求像身份验证那样只能使用电话号码作为收件人。
每个托管目录中的实用模板仅以 on_missing_language: fail 注册在 en 中。请求目录中未存储的语言会导致发送失败,而不会回退到英语或任何其他语言。
发送实用模板
使用 POST /v1/whatsapp/messages 并传入一个指定目录 slug 的 template 对象:
const msg = await bird.whatsapp.send({
to: "+16505551234",
template: {
slug: "bird_order_confirmation",
language: "en",
components: [
{
type: "body",
parameters: [
{ type: "text", name: "ref", text: "A1B2C3D4" },
{ type: "text", name: "amount", text: "USD 49.99" },
],
},
],
},
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
template="bird_order_confirmation",
language="en",
components=[
{
"type": "body",
"parameters": [
{"type": "text", "name": "ref", "text": "A1B2C3D4"},
{"type": "text", "name": "amount", "text": "USD 49.99"},
],
}
],
)
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)
}
ref := "A1B2C3D4"
amount := "USD 49.99"
refName := "ref"
amountName := "amount"
components := []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
{Type: "text", Name: &refName, Text: &ref},
{Type: "text", Name: &amountName, Text: &amount},
},
}}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
Template: "bird_order_confirmation",
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')->setName('ref')->setText('A1B2C3D4'),
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('amount')->setText('USD 49.99'),
]),
];
$message = $bird->whatsapp->send(
to: '+16505551234',
template: 'bird_order_confirmation',
language: 'en',
components: $components,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"amount","text":"USD 49.99","type":"text"}],"type":"body"}]' \
--language en \
--template bird_order_confirmation \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"template": {
"components": [
{
"parameters": [
{
"name": "ref",
"text": "A1B2C3D4",
"type": "text"
},
{
"name": "amount",
"text": "USD 49.99",
"type": "text"
}
],
"type": "body"
}
],
"language": "en",
"slug": "bird_order_confirmation"
},
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"template": {
"slug": "bird_order_confirmation",
"language": "en",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"name": "ref",
"text": "A1B2C3D4"
},
{
"type": "text",
"name": "amount",
"text": "USD 49.99"
}
]
}
]
}
}'与所有托管模板一样,省略 from:Bird 会根据类别和地区选择发送号码,手动设置会返回 422 E15018 WhatsAppSenderNotAllowed。自行创建实用模板并发送的方式与任何自建模板发送相同;参阅使用模板发送了解通用约定。
填充变量
实用模板的参数是命名参数,与身份验证的单一位置验证码相反。每个参数都包含一个 name,命名参数在数组中的顺序没有意义。为每个实际包含占位符的块发送一个 components 条目;没有变量的正文无需为其添加 components 条目。
URL 按钮是唯一的例外:其变量始终是位置参数 {{1}},发送时携带的是裸值而非完整地址:
代码示例
{ "type": "button", "parameters": [{ "type": "text", "text": "A-4192" }] }费用
在客服会话窗口仍然开启时投递的实用模板可享受 Meta 的免费费率。Bird 的出站费用在消息处理阶段、提交之前收取。后续的已投递或已读回调决定是否产生 Meta 费用。估算总费用时请同时考虑这两部分。
请参阅费用与计费了解发送何时计费,以及 WhatsApp 定价了解费率。
注意事项
- Meta 可以主动将实用模板重新归类为营销类别,消息会按新的更高价格继续发送。自 2025 年 4 月起,已因错误分类被 Meta 警告过的企业不会收到任何提前通知;更改立即生效。请避免在实用模板的文案中使用促销语言、优惠或追加销售内容,因为这些正是触发重新归类的原因。参阅模板指南了解哪些内容会被视为促销。
- gif 请求头或 copy_code 按钮在营销类别之外会被拒绝。 两者都是营销专属组件;在实用模板中声明任一项都会失败。
- 自建模板的发送不会在计费前检查参数数量。 如果你在自己的模板上发送了错误数量的参数,消息会被接受并计费,然后被 Meta 拒绝。托管目录发送不存在这个问题。
- 发送方位于错误的 WhatsApp Business Account 时会在计费前被拒绝。 from 必须与模板位于同一账户上;否则发送失败 422 E15023 WhatsAppSenderWABAMismatch。
后续步骤
- WhatsApp 模板:浏览目录和通用的模板发送约定
- 身份验证模板:一次性验证码以及创建模板时的验证门槛
- 营销模板:促销发送以及创建模板所需的账户