ntfy Publishing: Priority, Tags, Scheduling & Actions

All messages have a priority, which defines how urgently your phone notifies you.

每条消息都有一个优先级（priority），它决定手机以多急迫的方式提醒你。

On Android, you can set custom notification sounds and vibration patterns on your phone to map to these priorities (see Android config).

在 Android 上，你可以在手机里为各优先级映射自定义提示音和震动模式（见 Android config 一节）。

The following priorities exist:

优先级共有以下几档：

You can set the priority with the header X-Priority (or any of its aliases: Priority, prio, or p).

用 HTTP 头 X-Priority 设置优先级（别名 Priority、prio、p 均可）。

You can tag messages with emojis and other relevant strings:

可以给消息打标签——既可以是表情，也可以是任意有意义的字符串：

• Emojis: If a tag matches an emoji short code, it'll be converted to an emoji and prepended to title or message.

• 表情：标签若命中某个 emoji 短码（short code），会被转成表情并加在标题或正文最前面。

• Other tags: If a tag doesn't match, it will be listed below the notification.

• 普通标签：没命中短码的标签，会罗列在通知下方。

This feature is useful for things like warnings (⚠️, ️🚨, or 🚩), but also to simply tag messages otherwise (e.g. script names, hostnames, etc.).

这个功能适合做警告类标记（⚠️、🚨、🚩），也适合单纯给消息归类（如脚本名、主机名等）。

Use the emoji short code list to figure out what tags can be converted to emojis.

哪些标签能转成表情，查官方的 emoji 短码列表即可。

You can set tags with the X-Tags header (or any of its aliases: Tags, tag, or ta). Specify multiple tags by separating them with a comma, e.g. tag1,tag2,tag3.

用 X-Tags 头设置标签（别名 Tags、tag、ta），多个标签用英文逗号隔开，如 tag1,tag2,tag3。

You can format messages using Markdown 🤩. That means you can use bold text, italicized text, links, images, and more.

消息可以用 Markdown 排版 🤩——粗体、斜体、链接、图片等都行。

Supported Markdown features (web app only for now): emphasis, links, images, code blocks and inline code, headings, lists, blockquotes, horizontal rules.

支持的 Markdown 特性（目前仅网页版渲染）：强调、链接、图片、代码块与行内代码、标题、列表、引用块、分隔线。

By default, messages sent to ntfy are rendered as plain text. To enable Markdown, set the X-Markdown header (or any of its aliases: Markdown, or md) to true (or 1 or yes), or set the Content-Type header to text/markdown.

默认按纯文本渲染。要启用 Markdown，把 X-Markdown 头（别名 Markdown、md）设为 true（或 1、yes），或把 Content-Type 头设为 text/markdown。

You can delay the delivery of messages and let ntfy send them at a later date.

可以延迟消息的投递，让 ntfy 在未来某个时刻才发出。

This can be used to send yourself reminders or even to execute commands at a later date (if your subscriber acts on messages).

可用来给自己定提醒，甚至定时执行命令（如果你的订阅端会根据消息触发动作）。

You can set the delivery time using the X-Delay header (or any of its aliases: Delay, X-At, At, X-In or In), either by specifying a Unix timestamp (e.g. 1639194738), a duration (e.g. 30m, 3h, 2 days), or a natural language time string (e.g. 10am, 8:30pm, tomorrow, 3pm, Tuesday, 7am, and more).

投递时刻用 X-Delay 头指定（别名 Delay、X-At、At、X-In、In），三种写法：Unix 时间戳（如 1639194738）、时长（如 30m、3h、2 days）、自然语言（如 10am、8:30pm、tomorrow、Tuesday 等）。

As of today, the minimum delay you can set is 10 seconds and the maximum delay is 3 days.

目前最短延迟 10 秒，最长 3 天（自架服务端可改此上限）。

You can update or replace a scheduled message before it is delivered by publishing a new message with the same sequence ID.

定时消息在送达前可以更新或替换：用相同的 sequence ID 再发一条即可。

When you do this, the original scheduled message is deleted from the server and replaced with the new one.

这么做时，原定时消息会从服务端删除，由新消息顶替。

This is particularly useful for implementing a watchdog that triggers when your script stops sending heartbeat messages. This mechanism is also called a dead man's switch.

这特别适合实现看门狗（watchdog）：脚本停止发心跳时自动触发警报——此机制也叫「死人开关」（dead man's switch）。

For example, you could schedule a message to be delivered in 5 minutes, but continuously update it every minute to push the delivery time further into the future. If your script or system stops running, the message will eventually be delivered as an alert.

例如：排一条 5 分钟后送达的消息，然后每分钟更新一次、不断把送达时刻往后推。脚本或系统一旦停摆，没人再推了，这条消息最终就会作为警报落地。

You can cancel a scheduled message before it is delivered by sending a DELETE request to the /<topic>/<sequence_id> endpoint, just like deleting notifications.

定时消息送达前可撤回：向 /<topic>/<sequence_id> 端点发 DELETE 请求即可，与删除普通通知同法。

Alternatively, you can send a GET request to /<topic>/<sequence_id>/delete.

也可以改发 GET 请求到 /<topic>/<sequence_id>/delete。

This will remove the scheduled message from the server so it will never be delivered, and emit a message_delete event to any subscribers.

撤回后消息从服务端移除、永不投递，并向所有订阅端广播一条 message_delete 事件。

You can define which URL to open when a notification is clicked.

可以指定点击通知时打开哪个 URL。

This may be useful if your notification is related to a Zabbix alert or a transaction that you'd like to provide the deep-link for.

典型用途：通知关联某条 Zabbix 告警或某笔交易时，附上直达链接（deep-link）。

To define a click action for the notification, pass a URL as the value of the X-Click header (or its alias Click).

做法：把 URL 作为 X-Click 头（别名 Click）的值传入。

If you pass a website URL (http:// or https://) the web browser will open. If you pass another URI that can be handled by another app, the responsible app may open.

传网页 URL（http:// 或 https://）则开浏览器；传其他 app 能接管的 URI（如 mailto:、geo:、twitter://），则由对应 app 打开。

You can add action buttons to notifications to allow yourself to react to a notification directly. This is incredibly useful and has countless applications.

可以在通知上加动作按钮，直接就地响应通知——极其好用，应用场景无穷。

You can control your home appliances (open/close garage door, change temperature on thermostat, ...), react to common monitoring alerts (clear logs when disk is full, ...), and many other things. The sky is the limit.

控制家电（开关车库门、调温控器温度……）、响应监控告警（磁盘满了一键清日志……），凡此种种，上限只在想象力。

As of today, the following actions are supported:

目前支持四种动作：

• view: Opens a website or app when the action button is tapped

• view：点按钮打开网站或 app

• broadcast: Sends an Android broadcast intent when the action button is tapped (only supported on Android)

• broadcast：点按钮发 Android 广播 intent（仅 Android），可接 Tasker/MacroDroid 等自动化 app

• http: Sends HTTP POST/GET/PUT request when the action button is tapped

• http：点按钮直接发 HTTP POST/GET/PUT 请求——按钮即遥控器

• copy: Copies a given value to the clipboard when the action button is tapped

• copy：点按钮把指定值复制进剪贴板（适合一次性验证码；仅网页版与 Android）

You can define up to three user actions in your notifications, using either of the following methods: in the X-Actions header, using a simple comma-separated format; or as a JSON array in the actions key, when publishing as JSON.

每条通知最多定义三个动作，两种写法：X-Actions 头里用逗号分隔的简写格式；或 JSON 发布时写进 actions 键的 JSON 数组。

To define actions using the X-Actions header (or any of its aliases: Actions, Action), use the following format:

用 X-Actions 头（别名 Actions、Action）定义动作，格式如下：

Multiple actions are separated by a semicolon (;), and key/value pairs are separated by commas (,). Values may be quoted with double quotes (") or single quotes (') if the value itself contains commas or semicolons.

多个动作之间用分号（;）隔开，键值对之间用逗号（,）；值本身含逗号或分号时，用双引号或单引号包起来。

Each action type has a short format where some key prefixes can be omitted:

每种动作都有可省略键名前缀的简写格式：

Alternatively, the same actions can be defined as JSON array, if the notification is defined as part of the JSON body (see publish as JSON):

同样的动作也可以写成 JSON 数组——前提是整条通知用 JSON 体发布（中文标题必须走这条路，HTTP 头只收 ASCII）：

The http action sends a HTTP request when the action button is tapped. You can use this to trigger REST APIs for whatever systems you have, e.g. opening the garage door, or turning on/off lights.

http 动作在点按钮时发出 HTTP 请求，可触发你手头任何系统的 REST API——开车库门、开关灯之类。

By default, this action sends a POST request (not GET!), though this can be changed with the method parameter. The only required parameter is url. Headers can be passed along using the headers parameter.

默认发 POST（注意不是 GET！），可用 method 参数改；唯一必填参数是 url；请求头用 headers 参数带。

The copy action copies a given value to the clipboard when the action button is tapped. This is useful for one-time passcodes, tokens, or any other value you want to quickly copy without opening the full notification.

copy 动作在点按钮时把指定值复制进剪贴板——一次性验证码、token 等不必点开通知就想拿走的值，最合适。