WhatsApp 实用类模板
实用类模板用于跟进收件人已经完成的操作,例如下单、付款、预订或登录。Bird 的目录提供八个此类模板,其中包括 bird_signin_alert 和 bird_delivery_update。请以模板列表中标注的类别为准,不要根据 slug 名称判断类别:bird_signin_alert 看起来像身份验证模板,但实际属于实用类。
发送前准备
选择一个托管目录模板,或在已连接的企业账户上创建实用类模板。
与身份验证模板相同,发送 Bird 目录中提供的模板无需你完成任何验证。自行创建实用类模板同样无需验证:与身份验证模板不同,Meta 的企业验证要求从不适用于实用类模板,因此你可以在未验证的工作区中创建和编辑实用类模板。关于验证在其他方面解锁的功能,请参阅 WhatsApp 企业验证。
to 可以是 E.164 格式的电话号码,也可以是企业范围内的用户 ID。实用类模板不包含 OTP 按钮,因此不像身份验证模板那样要求收件人必须是电话号码。
所有托管目录实用类模板都只以 en 注册,即 on_missing_language: fail。如果请求目录中没有的语言,发送会直接失败,而不会回退到英语或其他语言。
发送实用类模板
POST /v1/whatsapp/messages,并附带一个指定目录 slug 的 template 对象:
const msg = await bird.whatsapp.send({
to: "+16505551234",
template: {
slug: "bird_order_confirmation",
language: "en",
parameters: { ref: "A1B2C3D4", amount: "USD 49.99" },
},
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
template="bird_order_confirmation",
language="en",
parameters={"ref": "A1B2C3D4", "amount": "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)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
Template: "bird_order_confirmation",
Language: "en",
Parameters: map[string]any{"ref": "A1B2C3D4", "amount": "USD 49.99"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$message = $bird->whatsapp->send(
to: '+16505551234',
template: 'bird_order_confirmation',
language: 'en',
parameters: ['ref' => 'A1B2C3D4', 'amount' => 'USD 49.99'],
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--language en \
--parameters '{"amount":"USD 49.99","ref":"A1B2C3D4"}' \
--template bird_order_confirmation \
--to +16505551234curl -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",
"parameters": {
"ref": "A1B2C3D4",
"amount": "USD 49.99"
}
}
}'与所有托管模板一样,请省略 from:Bird 会根据类别和地区选择发送号码,如果设置了该字段,则会返回 422 E15018 WhatsAppSenderNotAllowed。自行创建并发送实用类模板的方式与其他自建模板的发送方式相同;通用约定请参阅使用模板发送。
填写变量
实用类模板的变量是命名变量,因此每个变量在 parameters 中都是独立的键,例如 ref 和 amount。带编号 {{1}} 后缀的 URL 按钮改用 button_url 键。命名后缀则使用其自身的名称。发送时只传入值本身,而不是完整地址:
{ "parameters": { "ref": "A1B2C3D4", "button_url": "A-4192" } }components 发送则需要逐一命名每个正文参数,命名参数在数组中的顺序没有任何意义。关于组件、sub_type 的通用规则,以及发送中的 components 如何与模板声明的占位符对应,请参阅使用模板发送和组件与参数。
费用
在开放的客户服务窗口内送达的实用类模板,在 2026 年 9 月 30 日之前享受 Meta 的免费费率;自 2026 年 10 月 1 日起,Meta 会像对待其他实用类模板一样对其收费(2026 年 10 月定价变更)。Bird 的出站费用在消息处理期间、提交之前收取。之后的已送达或已读回调决定是否产生 Meta 费用。估算总费用时,请同时计入这两部分。
关于发送何时计费,请参阅费用与计费;关于费率,请参阅 WhatsApp 定价。
注意事项
- Meta 可以主动将实用类模板重新归类为营销类模板,消息会继续按更高的新价格发送。自 2025 年 4 月起,已因归类错误被 Meta 警告过的企业不会收到任何提前通知,变更立即生效。请勿在实用类模板的文案中加入促销用语、优惠或追加销售内容,因为这些内容会触发重新归类。关于哪些内容会被视为促销,请参阅模板指南。
gif标题或copy_code按钮在营销类模板之外会被拒绝。 两者都是营销类专用组件,在实用类模板上声明其中任何一个都会失败。- 自行创建的模板以
components方式发送时,不会在计费前检查参数数量。 如果在自己的模板上通过components传入了错误数量的参数,消息会被接受并计费,随后被 Meta 拒绝。缺少必需键的parameters发送会在计费前被拒绝,托管目录模板的发送也不存在这一问题。 - 位于错误 WhatsApp Business Account 上的发送方会在计费前被拒绝。
from必须与模板位于同一账户;否则发送会失败,并返回422E15023WhatsAppSenderWABAMismatch。
后续步骤
- WhatsApp 模板:浏览目录,以及通用的模板发送约定
- 身份验证模板:一次性验证码,以及创建此类模板时的验证门槛
- 营销模板:促销消息发送,以及创建此类模板所需的账号