From 94eb121f38f79d6d4a09c5e259d0c6eac6225f03 Mon Sep 17 00:00:00 2001 From: binwiederhier Date: Thu, 15 Jan 2026 13:07:07 -0500 Subject: [PATCH] Docs updates --- docs/publish.md | 104 +++++++++++++++++++++--------------------------- 1 file changed, 46 insertions(+), 58 deletions(-) diff --git a/docs/publish.md b/docs/publish.md index 0652fbd8..3363063a 100644 --- a/docs/publish.md +++ b/docs/publish.md @@ -946,19 +946,24 @@ _Supported on:_ :material-android: :material-firefox: You can **update, clear (mark as read and dismiss), or delete notifications** that have already been delivered. This is useful for scenarios like download progress updates, replacing outdated information, or dismissing notifications that are no longer relevant. -* Updating notifications will alter the content of an existing notification. -* Clearing notifications will mark them as read and dismiss them from the notification drawer. -* Deleting notifications will remove them from the notification drawer and remove them in the clients as well (if supported). +* [Updating notifications](#updating-notifications) will alter the content of an existing notification. +* [Clearing notifications](#clearing-notifications) will mark them as read and dismiss them from the notification drawer. +* [Deleting notifications](#deleting-notifications) will remove them from the notification drawer and remove them in the clients as well (if supported). -The way this works is that when you publish a message with a specific **sequence ID**, clients that receive the -notification will treat it as part of a sequence. When a new message with the same sequence ID is published, clients -will update the existing notification instead of creating a new one. You can also +Here's an example of a download progress notification being updated over time on Android:
+To facilitate updating notifications and altering existing notifications, ntfy messages are linked together in a sequence, +using a **sequence ID**. When a notification is meant to be updated, cleared, or deleted, you publish a new message with the +same sequence ID and the clients will perform the appropriate action on the existing notification. + +Existing ntfy messages will not be updated on the server or in the message cache. Instead, a new message is created that indicates +the update, clear, or delete action. This append-only behavior ensures that message history remains intact. + ### Updating notifications To update an existing notification, publish a new message with the same sequence ID. Clients will replace the previous notification with the new one. You can either: @@ -968,7 +973,7 @@ notification with the new one. You can either: `X-Sequence-ID` header (or any of its aliases: `Sequence-ID` or`SID`) If you don't know the sequence ID ahead of time, you can publish a message first and then use the returned -message `id` to update it. The message ID of the first message will then serve as the sequence ID for subsequent updates: +message `id` to update it. Here's an example: === "Command line (curl)" ```bash @@ -1115,8 +1120,8 @@ message `id` to update it. The message ID of the first message will then serve a ])); ``` -You can also use a custom sequence ID (e.g., a download ID, job ID, etc.) when publishing the first message. This is -less cumbersome, since you don't need to capture the message ID first. Just publish directly to +You can also use a **custom sequence ID** (e.g., a download ID, job ID, etc.) when publishing the first message. +**This is less cumbersome**, since you don't need to capture the message ID first. Just publish directly to `//`: === "Command line (curl)" @@ -1145,12 +1150,13 @@ less cumbersome, since you don't need to capture the message ID first. Just publ === "HTTP" ``` http + # Publish a message with a custom sequence ID POST /mytopic/my-download-123 HTTP/1.1 Host: ntfy.sh Downloading file... - ``` - ``` http + + # Update again using the X-Sequence-ID header POST /mytopic HTTP/1.1 Host: ntfy.sh X-Sequence-ID: my-download-123 @@ -1247,12 +1253,24 @@ less cumbersome, since you don't need to capture the message ID first. Just publ ])); ``` -You can also set the sequence ID via the `sid` query parameter, or when [publishing as JSON](#publish-as-json) -using the `sequence_id` field. +You can also set the sequence ID via the `sequence-id` [query parameter](#list-of-all-parameters), or when +[publishing as JSON](#publish-as-json) using the `sequence_id` field. + +If the message ID (`id`) and the sequence ID (`sequence_id`) are different, the ntfy server will include the `sequence_id` +field the response. A sequence of updates may look like this (first example from above): + +```json +{"id":"xE73Iyuabi","time":1673542291,"event":"message","topic":"mytopic","message":"Downloading file..."} +{"id":"yF84Jzvbcj","time":1673542295,"event":"message","topic":"mytopic","sequence_id":"xE73Iyuabi","message":"Download 50% ..."} +{"id":"zG95Kawdde","time":1673542300,"event":"message","topic":"mytopic","sequence_id":"xE73Iyuabi","message":"Download complete"} +``` ### Clearing notifications -To clear a notification (mark it as read and dismiss it from the notification drawer), send a PUT request to -`///clear` (or `///read` as an alias): +Clearing a notification means **marking it as read and dismissing it from the notification drawer**. + +To do this, send a PUT request to the `///clear` endpoint (or `///read` as an alias). +This will then emit a `message_clear` event that is used by the clients (web app and Android app) to update the read status +and dismiss the notification. === "Command line (curl)" ```bash @@ -1295,13 +1313,17 @@ To clear a notification (mark it as read and dismiss it from the notification dr ])); ``` -This publishes a `message_clear` event, which tells clients to: +An example response from the server with the `message_clear` event may look like this: -- Mark the notification as read in the app -- Dismiss the browser/Android notification +```json +{"id":"jkl012","time":1673542305,"event":"message_clear","topic":"mytopic","sequence_id":"my-download-123"} +``` ### Deleting notifications -To delete a notification entirely, send a DELETE request to `//`: +Deleting a notification means **removing it from the notification drawer and from the client's database**. + +To do this, send a DELETE request to the `//` endpoint. This will emit a `message_delete` event +that is used by the clients (web app and Android app) to remove the notification entirely. === "Command line (curl)" ```bash @@ -1344,51 +1366,16 @@ To delete a notification entirely, send a DELETE request to `//