Sign inGet started

WhatsApp 实用模板

实用模板用于跟进收件人已完成的操作:订单、付款、预约、登录。Bird 的目录中存有八个此类模板,包括 bird_signin_alertbird_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);
与所有托管模板一样,省略 from:Bird 会根据类别和地区选择发送号码,手动设置会返回 422 E15018 WhatsAppSenderNotAllowed。自行创建实用模板并发送的方式与任何自建模板发送相同;参阅使用模板发送了解通用约定。

填充变量

实用模板的参数是命名参数,与身份验证的单一位置验证码相反。每个参数都包含一个 name,命名参数在数组中的顺序没有意义。为每个实际包含占位符的块发送一个 components 条目;没有变量的正文无需为其添加 components 条目。
URL 按钮是唯一的例外:其变量始终是位置参数 {{1}},发送时携带的是裸值而非完整地址:
代码示例
{ "type": "button", "parameters": [{ "type": "text", "text": "A-4192" }] }
关于组件、sub_type 的通用规则,以及发送中的 components 如何与模板声明的占位符对应,请参阅使用模板发送组件与参数

费用

在客服会话窗口仍然开启时投递的实用模板可享受 Meta 的免费费率。Bird 的出站费用在消息处理阶段、提交之前收取。后续的已投递或已读回调决定是否产生 Meta 费用。估算总费用时请同时考虑这两部分。
请参阅费用与计费了解发送何时计费,以及 WhatsApp 定价了解费率。

注意事项

  • Meta 可以主动将实用模板重新归类为营销类别,消息会按新的更高价格继续发送。自 2025 年 4 月起,已因错误分类被 Meta 警告过的企业不会收到任何提前通知;更改立即生效。请避免在实用模板的文案中使用促销语言、优惠或追加销售内容,因为这些正是触发重新归类的原因。参阅模板指南了解哪些内容会被视为促销。
  • gif 请求头或 copy_code 按钮在营销类别之外会被拒绝。 两者都是营销专属组件;在实用模板中声明任一项都会失败。
  • 自建模板的发送不会在计费前检查参数数量。 如果你在自己的模板上发送了错误数量的参数,消息会被接受并计费,然后被 Meta 拒绝。托管目录发送不存在这个问题。
  • 发送方位于错误的 WhatsApp Business Account 时会在计费前被拒绝。 from 必须与模板位于同一账户上;否则发送失败 422 E15023 WhatsAppSenderWABAMismatch

后续步骤