# 优先级与关键警报

每条 Pocket Alert 消息都带有优先级，决定它以多大的动静送达：静默地出现在通知栏、以普通横幅提醒，或作为穿透静音开关和勿扰模式的关键警报唤醒设备。

## 五个级别

| 级别 | 别名 | 行为 |
|-------|---------|----------|
| `silent` | `min`, `-2` | 仅投递到通知栏，无声音、无振动 |
| `low` | `-1` | 安静送达，不打断 |
| `default` | `normal`, `0`（或省略） | 标准横幅 + 声音 |
| `high` | `1` | 时效性通知，可穿透专注模式和定时摘要 |
| `critical` | `max`, `urgent`, `2` | 穿透静音开关和勿扰模式唤醒设备 |

两种写法在所有地方都适用：可以发送 `"level": "critical"`，也可以发送 `"level": 2`。在 [创建消息](https://info.pocketalert.app/api/messages/create.md) API 中，该字段也接受 `priority` 作为名称；Webhook 只读取 `level`。

## 每个级别在设备上的表现

**iOS** 会将各级别映射为 APNs 的中断级别，即 `passive`、`active`、`time-sensitive` 和 `critical`。`critical` 警报使用 Apple 的关键警报权限，即使响铃开关关闭、勿扰模式开启，也会以独立音量播放声音。iOS 会单独请求**关键警报**权限；如果你在**设置 → 通知 → Pocket Alert** 中将其关闭，`critical` 消息会以 `time-sensitive` 的形式送达。

**Android** 会将各级别映射到不同的通知渠道。`critical` 使用高重要性渠道，可绕过勿扰模式并使用全屏 Intent，因此警报会直接占满屏幕，而不是停留在通知栏里等待。

由于每个级别对应一个独立的 Android 渠道，用户可以在系统设置中静音你的常规通知，同时保留关键通知的提醒。

## 在哪里设置

优先级按以下顺序解析，首个匹配项生效：

1. **单条消息** — [创建消息](https://info.pocketalert.app/api/messages/create.md) 中的 `level` 字段、控制台中的优先级选择器，或发送到 Webhook 的负载中的顶层 `level` 字段。
2. **单个 Webhook** — 在 Webhook 上设置的默认级别，适用于通过它接收的消息，因此传入的负载可以直接映射为严重程度。
3. **单个应用** — 在应用上设置的默认级别，适用于所有未自行指定级别的消息。
4. **兜底** — `default`。

正是这种顺序让同一个 Webhook 既能处理日常事件，也能处理紧急事件：将 Webhook 设为 `high`，当真正出问题时，再由单次调用将级别提升上去。

## 套餐限制

> **Warning: 关键级别为付费功能**
>
> 在免费套餐中，`critical` 会自动降级为 `high`，而不是被拒绝。警报仍然会送达，只是无法穿透勿扰模式。其他所有级别在任何套餐中都可用。

未知的级别名称，或超出 `-2`..`2` 范围的整数，会返回 `400`。

## 在应用中按优先级筛选

移动端消息列表使用相同的级别。点击筛选图标即可选择一个或多个级别、缩小到某个日期范围，或将整个列表按严重程度而非时间排序。当你拿起手机时发现有四十条通知，而只想看那两条真正重要的，这个功能就很有用。

## 如何选择级别

以下经验法则可以让通知保持可信：

- **`critical`** — 有人必须立即处理，无论几点。生产环境宕机、安全漏洞、冷库温度超标。
- **`high`** — 需要在一小时内关注。部署失败、支付被拒、队列积压。
- **`default`** — 今天值得知道。构建完成、新用户注册、表单已提交。
- **`low`** / **`silent`** — 仅作为记录送达手机。cron 任务按时完成、每晚备份已完成。

设置优先级的目的不是让每条警报都更响亮，而是让响亮的那些真正有意义。

## 相关内容

- [创建消息](https://info.pocketalert.app/api/messages/create.md) — `level` 字段与完整请求参考
- [操作按钮](https://info.pocketalert.app/features/action-buttons.md) — 无需打开应用即可处理警报
- [定时发送](https://info.pocketalert.app/features/scheduled-delivery.md) — 现在发送，稍后送达
