# 关键词规则

Bird 内置了关键词目录，因此收件人向您的可接收入站消息的号码回复 `STOP` 即可退订，无需您做任何配置。`START` 则撤销退订。您自己创建的规则会在其适用范围内覆盖 Bird 的默认行为。

本页介绍 Bird 识别哪些关键词、入站消息如何匹配，以及如何更改回复措辞或添加关键词。[**Keywords**](https://bird.com/dashboard/w/whatsapp/keyword-rules) 页面是仪表板中的对应功能。

![关键词规则列表，工作区规则显示在其所覆盖的默认规则上方](/images/docs/dashboard-whatsapp-keyword-rules.png)

## Bird 默认识别的关键词

九个词触发退订：

`stop`、`stop all`、`stopall`、`unsubscribe`、`cancel`、`end`、`quit`、`revoke`、`optout`

两个词撤销退订：`start` 和 `unstop`。

匹配针对整条消息而非子字符串。因为 `cancel` 和 `end` 是关键词，这一区别很重要："cancel my 3pm delivery" 是普通消息而非撤回同意。字母大小写、重音符号、多余空格和尾部标点会被忽略，因此 `Stop!` 和 `STOP` 都能匹配。词前或词中的标点不会被忽略，因此 `#stop` 不会匹配。

## 不匹配关键词的情形

群组消息中的关键词会被跳过，因此参与者无法通过在群组中回复来退订。请在您自己的发送逻辑中处理群组成员明确表达的退订请求。

## 偏好设置的记录时机

分类与 `whatsapp.received` 事件同步执行，而非先于该事件。因此，监听该事件的集成可能会在偏好设置记录完成之前就看到 `STOP` 到达。如果您的处理程序在收到入站消息后触发发送操作，请重新读取收件人的记录，而非假设事件顺序。

## 查看生效的规则

`GET /v1/whatsapp/keyword-rules` 描述了您的号码收到回复后的处理方式。不加过滤时，它会返回 Bird 的目录以及您创建的所有规则。可使用 `country`、`waba`、`operation` 或 `scope` 来缩小范围：

- `scope=system` 返回 Bird 的目录，包括被您的规则覆盖的默认规则。
- `scope=workspace` 返回您自己的规则。

**TypeScript**

```typescript
const rules = await bird.whatsapp.keywordRules.list({ operation: "opt_out" });
for (const rule of rules.data ?? []) {
  console.log(rule.scope, rule.effective_keywords);
}
```

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

规则按最具体优先的顺序返回，这也是入站消息的匹配顺序。每条规则携带 `effective_keywords`：Bird 针对该操作和国家/地区的关键词集，加上您添加的任何关键词。

对于没有 `country` 的自建规则，`effective_keywords` 会显示 Bird 的全球关键词集，因为该规则没有指定国家/地区，而发送者的国家/地区在消息到达前是未知的。该规则实际匹配的是 Bird 针对发送者所在国家/地区的关键词集，可能是更大的集合。在规则上设置 `country`，即可查看这些发送者实际匹配的关键词。

`country` 是发送者的国家/地区，根据其本人的电话号码而非其发送目标号码推断。这是 WhatsApp 发送的国家/地区信号。通过业务范围用户 ID 标识的发送者不携带国家/地区信息，因此其消息会跳过按国家/地区限定的规则，转而匹配全球规则。

## 更改回复

Bird 的默认回复内容正确但较为通用。要以您自己的名义回复，请创建规则：

**TypeScript**

```typescript
const rule = await bird.whatsapp.keywordRules.create({
  operation: "opt_out",
  country: "US", // the SENDER's country, from their own number
  reply: "You're off the list. ACME Courier won't message you again.",
});
// effective_keywords is Bird's set plus any of your own.
console.log(rule.id, rule.effective_keywords);
```

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

您的规则会替换该范围内 Bird 的回复，同时保留 Bird 的关键词。您的 `keywords` 是在现有关键词基础上的追加而非替换，因此 Bird 以后新增的关键词会自动开始匹配，无需您做任何更改。

如果要在记录退订的同时不发送任何回复，请在创建规则时省略 `reply`。如果要将已有规则静默，请在下方更新操作的 JSON 请求体中将 `reply` 设为 `null`；CLI 标志无法携带 `null`。

![添加关键词规则的对话框，包含额外关键词和回复内容的字段](/images/docs/dashboard-whatsapp-keyword-rule-dialog.png)

## 添加自定义关键词

**TypeScript**

```typescript
// Omitting keywords leaves the set alone; an empty array clears your additions
// back to Bird's. reply: null switches the auto-reply off and still records
// the opt-out.
const rule = await bird.whatsapp.keywordRules.update("wkr_01m2kj8x4te9p0rr7e5w2n1abc", {
  keywords: ["no more texts", "remove me"],
});
console.log(rule.effective_keywords);
```

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

省略 `keywords` 会保留您已添加的关键词不变。发送空数组会将关键词清除，恢复为 Bird 的默认集合。

## 规则范围与重复

规则可通过 `waba` 缩小到一个 WhatsApp Business Account，通过 `country` 缩小到一个发送者国家/地区，也可同时指定两者，或都不指定。每个操作、国家/地区和帐户的组合只能有一条规则。对同一组合的第二次写入会返回重复错误。

Bird 会拒绝将 `stop` 绑定到 `opt_in` 的规则，无论该词来自 Bird 的目录还是您的其他规则，因此退订关键词不能被用于授予同意。

## 删除规则

删除您的规则会将该范围交给匹配顺序中的下一条规则，而下一条规则不一定是您创建的。匹配顺序如下：

1. 您针对特定帐户和国家/地区的规则。
2. 您针对特定帐户的规则。
3. 您针对特定国家/地区的规则。
4. Bird 针对发送者所在国家/地区的规则。
5. 您的全球规则。
6. Bird 的全球规则。

因此，删除您针对某个国家/地区的规则后，该范围会先交给 Bird 针对该国家/地区的规则，而非您自己的全球规则：

**TypeScript**

```typescript
// The next rule in the ladder answers the scope, which is another rule of yours if you hold a less specific one; STOP never stops working.
await bird.whatsapp.keywordRules.delete("wkr_01m2kj8x4te9p0rr7e5w2n1abc");
```

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

删除规则不会使 `STOP` 停止工作。它只是将回复措辞和关键词集恢复为匹配顺序中下一条规则的内容。

## 后续步骤

- [偏好设置](/docs/guides/whatsapp/opt-outs/preferences)：关键词创建的记录，以及哪些记录可以撤销。
- [屏蔽列表](/docs/guides/whatsapp/opt-outs/suppressions)：您的工作区直接屏蔽的地址。
- [SMS 的退订与关键词](/docs/guides/sms/opt-outs-and-keywords)：另一渠道上的相同机制，还支持帮助和活动关键词。

## 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](/whatsapp-api) (product)

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