# 偏好设置

偏好设置是关于某人意愿的声明，记录在其某一渠道的标识上。在 WhatsApp 上，标识是 E.164 格式的电话号码。它与[屏蔽](/docs/guides/whatsapp/opt-outs/suppressions)是独立的记录，发送前两者都会被检查。

偏好设置通过三种方式到达你的工作区：WhatsApp 报告一条、收件人输入关键词、或你自行录入。你能对每条做什么取决于声明者是谁。

## 偏好设置包含的内容

声明要么是 `revoked`（退订），要么是 `granted`（同意）。

声明还包含覆盖范围，决定它拦截多少流量。`non_transactional` 覆盖营销及其他非必要消息，而交易类消息（如收据和验证码）不受影响。`all` 覆盖所有消息。**Preferences** 选项卡在 **Covers** 列中将它们显示为 **Non-transactional** 和 **All messages**。

声明可以通过 `sender_scope` 缩小到单个发送方，在 WhatsApp 上该字段标识商业帐户。如果不指定，声明将覆盖整个工作区的该渠道，包括你之后连接的帐户。

一个人可以在同一渠道上拥有多行记录，例如一条渠道范围的退订和一条发送方范围的退订并存。最严格的声明决定消息是否发出。

## Bird 为你记录的偏好设置

当 Bird 收到 Meta 事件表明收件人已停止接收营销消息时，会为该 WhatsApp Business Account 记录一条来源为收件人的偏好设置。该偏好设置覆盖非交易类消息。它不会创建全消息屏蔽，也不会将该人从你工作区中的所有帐户退订。

收件人也可以通过回复 `STOP` 来声明同样的意愿。该偏好设置的作用域是他们所回复的商业帐户，与上述一致。它覆盖所有消息，因为输入的 `STOP` 比 WhatsApp 的营销退订范围更广。请参阅[关键词规则](/docs/guides/whatsapp/opt-outs/keyword-rules)，了解 Bird 识别哪些关键词以及如何更改回复内容。

之后的恢复事件会更新该帐户的偏好设置。屏蔽和其他适用的偏好设置仍然生效，因此仅凭恢复事件并不能证明可以发送消息。

## 你录入的偏好设置

打开 [**Suppressions**](https://bird.com/dashboard/w/whatsapp/suppressions) 页面并切换到 **Preferences** 选项卡。在该选项卡中选择 **Every business account in the workspace** 录入一条记录，即可阻止该地址从你持有的所有帐户（包括之后连接的帐户）接收 WhatsApp 消息。

![已选择加入或退出的订阅者列表，显示每条声明的覆盖范围](/images/docs/dashboard-whatsapp-preferences.png)

该选项卡上的 **Record opt-out** 对话框录入的是全消息覆盖范围。

![用于记录退出的对话框，已选择工作区范围](/images/docs/dashboard-whatsapp-preference-new.png)

如果只需要停止营销消息，请使用工作区范围的 **Contacts** > **Preferences** 页面，其对话框同时提供 **Marketing messages** 和 **All messages** 选项。

## 通过代码读取偏好设置

`GET /v1/preferences` 返回工作区已记录的偏好设置，按创建时间从新到旧排列。传入 `channel=whatsapp` 可缩小到该渠道，再配合 `handle` 可在发送消息前查询某个号码的所有记录：

**TypeScript**

```typescript
for await (const preference of bird.preferences.list({
  channel: "whatsapp",
  handle: "+15550001234",
})) {
  console.log(preference.status, preference.coverage, preference.sender_scope);
}
```

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

`handle` 需要 `channel`，因为同一标识可能存在于多个渠道上。

## 通过代码录入偏好设置

`POST /v1/preferences` 录入一条声明。写入操作是基于渠道、标识和发送方作用域的 upsert，因此新声明会替换该键的当前记录：

**TypeScript**

```typescript
const result = await bird.preferences.create({
  channel: "whatsapp",
  handle: "+15550001234",
  status: "revoked",
  coverage: "non_transactional",
});
console.log(result.applied, result.preference?.id);
```

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

声明按做出时间排序，而非到达时间。API 会拒绝日期早于该键当前记录的声明，并返回 `applied: false` 以及留存的声明。被拒绝的声明保留在该键的历史中。

`201` 表示该键之前没有记录，此声明创建了一条。`200` 返回该键的留存记录，无论此声明是替换、重复还是被拒绝。

## 你可以撤销哪些

你录入的偏好设置可以在 **Preferences** 选项卡中删除，或在收件人要求恢复发送后通过 `DELETE /v1/preferences/{preference_id}` 删除。

收件人自行做出的声明只有他们自己能撤销。取消订阅或停止关键词在他们重新选择加入时结束，删除操作会返回 `422`。要在获得其同意后恢复发送，请录入一条携带 `consented_at`（即同意时刻）的 `granted` 声明。当该时刻晚于其所撤销的退订时，授权才会生效，因此它记录的是意愿变更，而非擦除原始声明。

删除操作与其他声明一样按接收时间排序。如果记录中包含在该时刻之后做出的声明，删除会被拒绝，并连同留存记录一起以 `applied: false` 返回。

## 投递错误先于事件到达时

运营商投递错误可能在 Bird 记录匹配事件之前就报告了停止。请保留收件人的选择，并调查偏好设置和事件历史，而不是将本地缺少记录当作可以发送的许可。

## 后续步骤

- [屏蔽](/docs/guides/whatsapp/opt-outs/suppressions)：你的工作区直接拦截的地址。
- [关键词规则](/docs/guides/whatsapp/opt-outs/keyword-rules)：在你的号码上录入偏好设置的关键词。
- [WhatsApp 事件](/docs/guides/whatsapp/events)：被拦截的发送所产生的 `whatsapp.rejected` 载荷。

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