操作按钮
一条通知最多可以带三个按钮。无需先读完提醒再打开电脑处理,直接在锁屏上操作即可:打开运行记录、触发重启、复制验证码。
三种类型
| 类型 | 按钮的作用 | 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 不会代理该请求,也不会读取响应正文。
幂等性由你负责
连续点击同一个 http 按钮两次,就会发送两次请求,我们不会拦截重复操作。如果重复触发代价很高,请让端点具备幂等性。
来自 Webhook 的按钮
Webhook 可以携带操作模板,其中的 %path% 占位符会从传入的载荷中取值填充。例如,Sentry 告警可以附带一个指向具体问题的 查看问题 按钮;Stripe 事件则可以附带一个指向对应收款的 查看付款 按钮。
替换后的值会先进行 JSON 转义,再解析模板,因此载荷字段中即使包含引号,也无法跳出并改写 URL。如果某个按钮解析结果无效,例如告警中没有 runbook URL 却出现了 Runbook 按钮,则只丢弃该按钮,其余按钮和消息照常送达。出错的按钮绝不会导致告警丢失。
创建或编辑 Webhook 时,可以在控制台中设置模板,也可以通过 Webhook API 设置。
限制与验证
- 每条消息最多 3 个按钮,按发送顺序显示。
actions数组经 JSON 编码后最多 2048 字节。它随推送一同发送,而推送上限为 4 KB,因此过长的message会被截短以腾出空间。view和http需要有效的http(s)URL。其他情况在 API 中返回400;在 Webhook 模板中则会丢弃无效按钮。- 未知的
type值返回400。
付费功能
免费套餐的消息会在服务端去除操作按钮,消息本身仍会正常送达。
相关链接
- 创建消息 —
actions数组与完整请求参考 - 优先级 — 提醒的响铃强度
- Webhook 设置 — 传入 Webhook 的操作模板