# WhatsApp 实用模板

实用模板用于跟进收件人已完成的操作：订单、付款、预约、登录。Bird 的目录中存有八个此类模板，包括 `bird_signin_alert` 和 `bird_delivery_update`。请根据模板列表中的分类而非名称来判断一个 slug 的类别：`bird_signin_alert` 看起来像身份验证模板，但实际上不是，它属于实用类别。

## 发送前准备

选择一个托管目录模板，或在已关联的商业账户上自行创建一个。

发送 Bird 预置的目录模板无需你进行任何验证，与身份验证类别相同。自行创建实用模板同样不需要验证：与身份验证不同，Meta 的企业验证门槛从不适用于实用类别，因此你可以在未验证的工作区上创建和编辑实用模板。参阅[WhatsApp 企业验证](/docs/knowledge-base/whatsapp/business-verification)了解验证在其他场景下的作用。

`to` 可以是 E.164 格式的电话号码或业务范围内的用户 ID。实用模板不包含 OTP 按钮，因此不要求像身份验证那样只能使用电话号码作为收件人。

每个托管目录中的实用模板仅以 `on_missing_language: fail` 注册在 `en` 中。请求目录中未存储的语言会导致发送失败，而不会回退到英语或任何其他语言。

## 发送实用模板

使用 `POST /v1/whatsapp/messages` 并传入一个指定目录 slug 的 `template` 对象：

**TypeScript**

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

Examples: [TypeScript](/zh-sg/wendang/guides/whatsapp/templates/utility.ts.md) · [Python](/zh-sg/wendang/guides/whatsapp/templates/utility.py.md) · [Go](/zh-sg/wendang/guides/whatsapp/templates/utility.go.md) · [PHP](/zh-sg/wendang/guides/whatsapp/templates/utility.php.md) · [CLI](/zh-sg/wendang/guides/whatsapp/templates/utility.cli.md) · [MCP](/zh-sg/wendang/guides/whatsapp/templates/utility.mcp.md) · [cURL](/zh-sg/wendang/guides/whatsapp/templates/utility.curl.md)

与所有托管模板一样，省略 `from`：Bird 会根据类别和地区选择发送号码，手动设置会返回 `422` [`E15018`](/docs/api/errors/E15018) `WhatsAppSenderNotAllowed`。自行创建实用模板并发送的方式与任何自建模板发送相同；参阅[使用模板发送](/docs/guides/whatsapp/templates#sending-with-a-template)了解通用约定。

## 填充变量

实用模板的参数是命名参数，与身份验证的单一位置验证码相反。每个参数都包含一个 `name`，命名参数在数组中的顺序没有意义。为每个实际包含占位符的块发送一个 `components` 条目；没有变量的正文无需为其添加 `components` 条目。

URL 按钮是唯一的例外：其变量始终是位置参数 `{{1}}`，发送时携带的是裸值而非完整地址：

```json
{ "type": "button", "parameters": [{ "type": "text", "text": "A-4192" }] }
```

关于组件、`sub_type` 的通用规则，以及发送中的 `components` 如何与模板声明的占位符对应，请参阅[使用模板发送](/docs/guides/whatsapp/templates#sending-with-a-template)和[组件与参数](/docs/guides/whatsapp/sending-whatsapp#components-and-parameters)。

## 费用

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

请参阅[费用与计费](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing)了解发送何时计费，以及 [WhatsApp 定价](/products/whatsapp/pricing)了解费率。

## 注意事项

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

## 后续步骤

- [WhatsApp 模板](/docs/guides/whatsapp/templates)：浏览目录和通用的模板发送约定
- [身份验证模板](/docs/guides/whatsapp/templates/authentication)：一次性验证码以及创建模板时的验证门槛
- [营销模板](/docs/guides/whatsapp/templates/marketing)：促销发送以及创建模板所需的账户

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)