Sign inGet Started

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

与所有托管模板一样,请省略 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 必须与模板位于同一账户;否则发送会失败,并返回 422 E15023 WhatsAppSenderWABAMismatch。

后续步骤

  • WhatsApp 模板:浏览目录,以及通用的模板发送约定
  • 身份验证模板:一次性验证码,以及创建此类模板时的验证门槛
  • 营销模板:促销消息发送,以及创建此类模板所需的账号