# 操作按钮

一条通知最多可以带三个按钮。无需先读完提醒再打开电脑处理，直接在锁屏上操作即可：打开运行记录、触发重启、复制验证码。

## 三种类型

| 类型 | 按钮的作用 | `value` 的内容 |
|------|----------------------|---------------|
| `view` | 打开 URL | URL，例如 `https://status.example.com` |
| `http` | 在后台发送 HTTP 请求 | JSON 字符串：`{"url":"…","method":"POST","headers":{…},"body":"…"}` |
| `copy` | 将文本复制到剪贴板 | 要复制的原始文本 |

对于 `http`，只有 `url` 是必填项，`method` 默认为 `GET`。当存在 `body` 且未设置内容类型时，会自动添加 `Content-Type: application/json`。

`http` 和 `copy` 无需打开应用即可运行，即使应用已关闭也一样。`view` 会将应用或浏览器切换到前台。

## 按钮显示的位置

无论应用处于前台、后台还是已关闭，按钮都会显示在 iOS 和 Android 的系统通知中，同时也会保留在消息本身里。后者很重要：即使把横幅划走，之后打开这条消息时按钮依然可用。

- **按钮标签**在两个平台上都会按你发送的内容原样显示。如果 iOS 无法及时准备自定义按钮，会回退为每种类型的通用标签，即 **打开**、**运行**、**复制**，按钮功能不受影响。
- **锁屏。** `http` 和 `copy` 无需解锁即可在锁屏上运行。`view` 会打开应用或浏览器，因此手机会先要求解锁。在 Android 上，只有锁屏设置为显示通知内容时，按钮才会出现在锁屏上。
- **请求失败。** 如果 `http` 请求失败（状态码非 2xx/3xx 或网络错误），会弹出一条带 **重试** 按钮的通知。可能已经到达你服务器的请求，不会被自动重试。
- **应用版本。** 系统通知按钮需要 Pocket Alert 应用 2.0.1 或更高版本。较旧的版本只会在消息内部显示按钮。

## 审批流程

两个 `http` 按钮 **批准** 和 **拒绝**，可以把一条通知变成一键操作面板。这种模式适用于任何需要等待人工确认的场景：

- 等待人工审批的部署流水线
- 在花钱或修改生产环境之前需要确认的 LLM 代理
- 超过某个金额的退款
- 门、闸机、灯、车库门

请求直接从手机发送到你的端点。Pocket Alert 不会代理该请求，也不会读取响应正文。

> **Warning: 幂等性由你负责**
>
> 连续点击同一个 `http` 按钮两次，就会发送两次请求，我们不会拦截重复操作。如果重复触发代价很高，请让端点具备幂等性。

## 来自 Webhook 的按钮

Webhook 可以携带操作模板，其中的 `%path%` 占位符会从传入的载荷中取值填充。例如，Sentry 告警可以附带一个指向具体问题的 **查看问题** 按钮；Stripe 事件则可以附带一个指向对应收款的 **查看付款** 按钮。

替换后的值会先进行 JSON 转义，再解析模板，因此载荷字段中即使包含引号，也无法跳出并改写 URL。如果某个按钮解析结果无效，例如告警中没有 runbook URL 却出现了 **Runbook** 按钮，则只丢弃该按钮，其余按钮和消息照常送达。出错的按钮绝不会导致告警丢失。

创建或编辑 Webhook 时，可以在控制台中设置模板，也可以通过 [Webhook API](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template) 设置。

## 限制与验证

- 每条消息最多 **3** 个按钮，按发送顺序显示。
- `actions` 数组经 JSON 编码后最多 **2048 字节**。它随推送一同发送，而推送上限为 4 KB，因此过长的 `message` 会被截短以腾出空间。
- `view` 和 `http` 需要有效的 `http(s)` URL。其他情况在 API 中返回 `400`；在 Webhook 模板中则会丢弃无效按钮。
- 未知的 `type` 值返回 `400`。

> **Warning: 付费功能**
>
> 免费套餐的消息会在服务端去除操作按钮，消息本身仍会正常送达。

## 相关链接

- [创建消息](https://info.pocketalert.app/api/messages/create.md) — `actions` 数组与完整请求参考
- [优先级](https://info.pocketalert.app/features/priority-levels.md) — 提醒的响铃强度
- [Webhook 设置](https://info.pocketalert.app/api/webhooks/settings.md) — 传入 Webhook 的操作模板
