ntfy 如何为通知添加动作按钮并配置 view 与 http 动作
【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy
如果你通过 ntfy 推送一条通知后，还需要点进 App 或网页才能做下一步操作（打开某个面板、调用一次 REST API），那就用不上动作按钮了。ntfy 允许在发布通知时附带最多三个动作按钮，用户在通知上直接点按即可触发。本文以官方文档docs/publish.md的 “Action buttons” 一节为主线，演示如何用X-Actions请求头或 JSON 请求体两种方式，配置view（打开网站/App）和http（发送 HTTP 请求）两种动作，并通过 JSON 订阅接口验证按钮定义是否随消息下发。
前提条件：你需要一个可发布的 ntfy 服务地址（如 ntfy.sh 或自建服务，安装方式见 安装文档）和一个主题名。主题无需预先创建，发布时即自动建立；由于没有注册环节，主题名本质上相当于密码，文档建议选一个不易被猜中的名字。动作按钮在 Android、iOS 和 Firefox 通知上受支持。
文档示例：带两个用户动作按钮的通知（来源：docs/publish.md）
动作按钮的两种定义方式
一条通知最多可以定义三个用户动作，写法有两种，任选其一：
- 在
X-Actions请求头中用逗号分隔的简单格式（请求头别名：Actions、Action）； - 以 JSON 请求体发布时，在
actions键中放一个 JSON 数组。
请求头格式分长短两种，多个动作之间用分号（;）分隔，键值对之间用逗号（,）分隔：
# 长格式 action=<action1>, label=<label1>, paramN=... [; action=<action2>, label=<label2>, ...] # 短格式 <action1>, <label1>, paramN=... [; <action2>, <label2>, ...]如果某个值本身包含逗号或分号，可以用双引号（"）或单引号（'）把值包起来。每种动作的短格式为：
view:view, <label>, <url>[, clear=true]http:http, <label>, <url>[, method=<method>][, headers.<header>=<value>][, body=<body>][, clear=true]
（另有broadcast、copy两种动作，本文不展开。）
配置 view 动作
view动作在按钮被点按时打开一个网站或 App：http:///https://打开浏览器（若某 App 注册了该 URL 则打开 App）；mailto:打开邮件应用；geo:打开 Google Maps；ntfy://打开 ntfy；twitter://打开 Twitter 等。具体如何路由取决于 Android 和桌面浏览器对链接的处理方式。
view动作支持的字段：
| 字段 | 必填 | 类型 | 默认值 | 示例 | 说明 |
|---|---|---|---|---|---|
action | ✔️ | string | - | view | 动作类型，必须是view |
label | ✔️ | string | - | Turn on light | 通知中动作按钮的标签 |
url | ✔️ | URL | - | https://example.com | 点按时打开的 URL |
clear | - | boolean | false | true | 点按动作按钮后清除通知 |
文档给出的 curl 示例（myhome为示例主题名，替换为你自己的主题）：
curl \ -d "Somebody retweeted your tweet." \ -H "Actions: view, Open Twitter, https://twitter.com/binwiederhier/status/1467633927951163392" \ ntfy.sh/myhome等价的 ntfy CLI 写法：
ntfy publish \ --actions="view, Open Twitter, https://twitter.com/binwiederhier/status/1467633927951163392" \ myhome \ "Somebody retweeted your tweet."短格式之外，也可以始终用<key>=<value>写法，例如action=view, url=https://google.com, label=Open Google。
配置 http 动作
http动作在按钮被点按时发送一个 HTTP 请求，文档给出的用途示例是触发 REST API（如开关车库门、控制灯光）。注意两点：
- 默认发送 POST 请求（不是 GET），可用
method参数改为其他方法； - 唯一必填的参数是
url，请求头通过headers参数传递。
http动作支持的字段：
| 字段 | 必填 | 类型 | 默认值 | 示例 | 说明 |
|---|---|---|---|---|---|
action | ✔️ | string | - | http | 动作类型，必须是http |
label | ✔️ | string | - | Open garage door | 通知中动作按钮的标签 |
url | ✔️ | string | - | https://ntfy.sh/mytopic | HTTP 请求发送到的 URL |
method | - | GET/POST/PUT/... | POST⚠️ | GET | 请求方法，默认是 POST⚠️ |
headers | - | map of strings | - | 见示例 | 请求携带的 HTTP 头；JSON 发布时为 map，简单格式用headers.<header>=<value> |
body | - | string | 空 | some body, somebody? | HTTP 请求体 |
clear | - | boolean | false | true | HTTP 请求成功后清除通知；请求失败则通知不会被清除 |
文档给出的 curl 示例（https://api.mygarage.lan/与 Bearer token 均为文档示例值）：
curl \ -d "Garage door has been open for 15 minutes. Close it?" \ -H "Actions: http, Close door, https://api.mygarage.lan/, method=PUT, headers.Authorization=Bearer zAzsx1sk.., body={\"action\": \"close\"}" \ ntfy.sh/myhome短格式为http, <label>, <url>（例如http, Close door, https://api.mygarage.lan/close）。
组合一条带两个动作的通知
下面把view和http组合在同一条通知里（文档示例，myhome替换为你自己的主题）：
body='{"temperature": 65}' curl \ -d "You left the house. Turn down the A/C?" \ -H "Actions: view, Open portal, https://home.nest.com/, clear=true; \ http, Turn down, https://api.nest.com/, body='$body'" \ ntfy.sh/myhome对应的 ntfy CLI 写法：
body='{"temperature": 65}' ntfy publish \ --actions="view, Open portal, https://home.nest.com/, clear=true; \ http, Turn down, https://api.nest.com/, body='$body'" \ myhome \ "You left the house. Turn down the A/C?"第二个动作里的body='$body'就是前面定义的 shell 变量，值中包含逗号和引号，靠引号包裹避免被解析成键值对分隔符。如果非 ASCII 字符在标题或动作里显示成?符号，文档说明可以把任意请求头（包括 actions）按 RFC 2047 编码，例如 base64 形式=?UTF-8?B?8J+HqfCfh6o=?=。
用 JSON 数组定义动作
发布时若在请求体中定义整条消息（JSON 发布），动作就是actions键下的 JSON 数组。注意文档的强调：JSON 发布必须 PUT/POST 到 ntfy 根 URL，而不是主题 URL——发到https://ntfy.sh/是正确做法，发到https://ntfy.sh/mytopic是不正确的。
curl ntfy.sh \ -d '{ "topic": "myhome", "message": "You left the house. Turn down the A/C?", "actions": [ { "action": "view", "label": "Open portal", "url": "https://home.nest.com/", "clear": true }, { "action": "http", "label": "Turn down", "url": "https://api.nest.com/", "body": "{\"temperature\": 65}" } ] }'JSON 请求体中与本场景相关的字段（完整字段表见 publish 文档 “Publish as JSON” 一节）：topic必填；actions为 JSON 数组，即上文的用户动作按钮；message为空时置为triggered。
验证动作是否随消息下发
文档提供的核对路径是订阅接口。用 JSON 方式订阅该主题，查看返回消息中的actions字段：
curl "ntfy.sh/myhome/json?poll=1"/json端点返回的每条消息都是 JSON，按 API 文档 的 JSON message format，actions字段是JSON array，内容为发布时定义的动作按钮。确认输出中actions数组包含你定义的view/http条目，说明动作定义已被服务器接收并随消息下发；之后在订阅该主题的 Android App、iOS 通知或 Firefox 通知中应能看到对应按钮，点按后分别触发打开链接、发送 HTTP 请求。
另外两个与验证相关的行为边界：
clear=true的动作在点按后清除该通知；http动作的clear只在请求成功时清除通知，请求失败时通知保留。
限制与边界
- 每条通知最多三个动作按钮；
view与http动作在 Android、iOS、Firefox 上受支持；文档列出的broadcast动作仅 Android 支持，copy动作的按钮只在 web app 和 Android App 通知列表中显示，浏览器桌面通知中不显示；http动作默认方法是 POST，如果你的目标接口只接受 GET，必须显式写method=GET；- 用请求头方式发布时，请求头别名
X-Actions/Actions/Action均可（见 参数总表）。
如果需要进一步定制消息内容（比如根据 webhook 载荷动态生成动作），文档的 “Message templating” 一节演示了模板语法；ntfy://深链接可用于view的url，让按钮直接打开 ntfy 的某个主题。
【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
