# 退订与关键词

当有人向您的某个号码发送短信时，Bird 会在您收到消息之前将其与关键词目录进行匹配。识别到的 **stop** 关键词会阻止该发送方向该订阅者发送后续消息，**start** 关键词会解除阻止，**help** 关键词会回复支持信息。受支持的国家/地区无需额外设置即可使用此功能。

本指南涵盖 Bird 的默认行为、如何查看该行为以及如何更改它。

## 默认行为

订阅者向您的某个号码发送 `STOP`。Bird：

1. 根据该号码所属国家/地区的关键词目录**识别该消息**。
2. 在该发送方与订阅者的精确配对上**记录一条抑制**。
3. 回复该国家/地区的退订消息以**确认操作**。

此后，该发送方向该订阅者的发送将被拒绝并返回 [`E12077 SMSRecipientSuppressed`](/docs/api/errors/E12077)，而非实际发出。`START` 会解除抑制并同样发送确认，`HELP` 则仅回复而不改变任何内容。

一条抑制仅覆盖**一个发送方和一个订阅者**，不会覆盖整个工作区。该阻止的技术范围并不意味着您有权使用另一个发送方。请将客户明确表达的偏好应用于其要求停止的消息和计划。如需一次性停止工作区中的所有发送方，请参阅下方的[退订所有发送方](#退订所有发送方)。

确认消息不受其所记录的抑制影响。即使新的抑制会阻止后续的出站发送，Bird 仍可回复入站消息。

## 覆盖范围按国家/地区划分

Bird 的目录覆盖**部分国家/地区**。在已覆盖的国家/地区，Bird 默认处理退订、订阅和帮助关键词。在未覆盖的国家/地区，Bird 不识别任何关键词、不发送回复、也不记录退订。如果您向未覆盖的国家/地区发送消息，则必须自行处理退订。

在依赖某个国家/地区之前，先检查其覆盖情况：

```bash
bird sms keyword-rules list --country NL
```

空结果表示该国家/地区没有覆盖。您可以在那里添加自己的 `custom` 关键词，但其他每种操作都是替换 Bird 内置的内容，因此只能为 Bird 目录中已有的国家/地区创建规则。

## 查看当前生效的规则

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

- `scope=system` 仅返回 Bird 的目录，包括被工作区规则替换的默认值。
- `scope=workspace` 仅返回您自己的规则。
- `number=+18005551234` 返回适用于您某个号码的规则，按应用于入站消息的顺序排列；添加 `from_country` 可查看从其他位置发送消息的发送方所匹配的规则，结果可能不同。

规则按从最具体到最一般的顺序返回，每条规则都包含 `effective_keywords`：Bird 为该操作和国家/地区设定的关键词集，加上您添加的内容。

该列表除 `stop`、`start` 和 `help` 之外还返回两种操作：

- `info` 回复您的计划信息，行为与 `help` 完全相同。它被单独设置，以便 INFO 回复需要与 HELP 回复不同的国家/地区可以同时使用两者；在 Bird 未为某个国家/地区提供 `info` 规则的情况下，INFO 是该国家/地区的 `help` 关键词之一，并使用 `help` 回复进行应答。
- `confirm` 标记双重订阅确认回复，例如 `JOIN` 或 `YES`。它目前不发送任何内容，请在您自己的处理程序中处理。Bird 持有这些关键词，以防止 `custom` 规则占用它们。

## 更改回复内容

Bird 的默认回复是正确的但较为通用。要以您自己的名义回复，请为该国家/地区和操作创建一条规则：

```bash
bird sms keyword-rules create \
  --operation stop \
  --country NL \
  --reply "You are unsubscribed from MyBrand. Reply START to resume."
```

您的规则会替换 Bird 在该国家/地区的默认回复，并**保留 Bird 的关键词**，除非您添加更多。它还会继承 Bird 之后添加的关键词。您不能更改分配给退订或订阅关键词的操作；Bird 会拒绝尝试将 `STOP` 绑定到其他操作的规则。

如果 Bird 以多种语言提供某个国家/地区的关键词，则每种语言都有各自的规则，因此创建时必须指定要替换的语言。加拿大就属于这种情况：其 `stop`、`start` 和 `help` 规则分别有 `en` 和 `fr` 两种版本。`language` 在此处是必需的，而对于 Bird 仅以单一语言提供的国家/地区则会被拒绝。

```bash
bird sms keyword-rules create \
  --operation stop \
  --country CA \
  --language fr \
  --reply "Vous etes desabonne de MyBrand. Repondez DEBUT pour reprendre."
```

列出某个国家/地区的规则可以查看是否存在语言拆分以及有哪些语言可用。

要将规则限定到一个号码而非您在该国家/地区持有的所有号码，请设置 `number` 而不是仅依赖国家/地区。

如果您从自己的系统而非通过 Bird 来回复这些消息，请将 `reply` 设为 null 并同时设置 `confirmed_self_managed`。这会关闭 Bird 对该规则的自动回复，而抑制本身继续生效。

## 活动关键词

`custom` 规则不带有内置行为。它们匹配您选择的关键词并发送您编写的回复，可用于支持 `PIZZA` 等活动关键词。`custom` 规则不继承任何关键词，因此至少需要一个自定义关键词，并且可以省略 `country` 以在您发送的所有地区生效。

Bird 已绑定到合规操作的关键词不能作为自定义关键词重复使用。

## 查看和管理抑制

`GET /v1/sms/suppressions` 列出当前被阻止发送消息的配对，最新的排在最前。按 `destination` 过滤可在发送前检查某个订阅者，按 `originator` 过滤可查看某个发送方，或按 `reason` 过滤：

- `keyword_stop`：订阅者发送了 stop 关键词。
- `carrier_opted_out`：其运营商上报了退订。
- `manual`：通过 API 或控制台添加。

已结束的抑制不会列出，因此响应结果标识的是您当前无法发送消息的收件人。

您可以手动添加一条抑制，以处理客户通过电话告知您的退订请求：

```bash
bird sms suppressions add --destination +15550001234 --originator +15557654321
```

手动抑制会阻止**所有类别，包括事务性消息**，且添加操作是幂等的。移除操作有意限定范围较窄：只有 `manual` 抑制可以通过此方式结束。订阅者自己的 stop 关键词和运营商的退订会被拒绝移除，因为这些不是您有权撤销的。

## 退订所有发送方

stop 关键词和上述手动抑制都只停止一个发送方。有些订阅者希望一次性退订工作区中的所有发送方，例如某人告诉您的支持团队停止所有短信，而非逐个号码回复。

这是一种明确表达的偏好而非抑制，因此它位于 **SMS** > **Suppressions** 的 **Preferences** 选项卡中，而不在上述列表中。打开该选项卡并使用**工作区中的所有发送方**记录退订：该号码将停止接收工作区中所有发送方（包括之后添加的发送方）的 SMS。在此选项卡上记录的退订覆盖所有消息，包括验证短信；如果只需停止营销类消息，请使用工作区级别的 **Contacts** > **Preferences** 页面，其对话框提供覆盖范围选择。

Bird 会先检查本指南中描述的抑制，因此普通关键词 stop 仍然像之前一样返回 `E12077` 拒绝。向已记录工作区级退订的号码发送消息时，会被以 [`E25000 PreferenceRevoked`](/docs/api/errors/E25000) 拒绝。要在订阅者要求后恢复发送，请从 Preferences 选项卡中移除该条目（是您记录的，所以您可以移除），或在工作区级别的 **Contacts** > **Preferences** 页面记录一条订阅。

## 后续步骤

在进行受众发送之前，请查阅[活动同意与发送控制](/products/sms/marketing/compliance)，或了解用于集成的 [SMS 退订处理](/products/sms/compliance/opt-out)。

- [发送 SMS](/docs/guides/sms/sending-sms)：查看类别、发送方和拒绝条件。
- [Events](/docs/guides/sms/events)：处理发送和回复的 `sms.*` 事件。
- [SMS 日志](/docs/guides/sms/sms-log)：检查消息详情，包括被拒绝的发送。

## Related resources

- [How do I collect SMS opt-ins?](/explained/sms/how-do-i-collect-sms-opt-ins) (answer)
- [Preview message segments](/tools/sms-segment-calculator) (tool)
- [SMS compliance](/sms-api/features/compliance) (product)
- [Operate messaging reliably](/learn/paths/reliability) (course)

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