AI docs, needs work
This commit is contained in:
binwiederhier
161
docs/publish.md
161
docs/publish.md
@@ -1418,22 +1418,23 @@ The JSON message format closely mirrors the format of the message you can consum
|
||||
(see [JSON message format](subscribe/api.md#json-message-format) for details), but is not exactly identical. Here's an overview of
|
||||
all the supported fields:
|
||||
|
||||
| Field | Required | Type | Example | Description |
|
||||
|------------|----------|----------------------------------|-------------------------------------------|-----------------------------------------------------------------------|
|
||||
| `topic` | ✔️ | *string* | `topic1` | Target topic name |
|
||||
| `message` | - | *string* | `Some message` | Message body; set to `triggered` if empty or not passed |
|
||||
| `title` | - | *string* | `Some title` | Message [title](#message-title) |
|
||||
| `tags` | - | *string array* | `["tag1","tag2"]` | List of [tags](#tags-emojis) that may or not map to emojis |
|
||||
| `priority` | - | *int (one of: 1, 2, 3, 4, or 5)* | `4` | Message [priority](#message-priority) with 1=min, 3=default and 5=max |
|
||||
| `actions` | - | *JSON array* | *(see [action buttons](#action-buttons))* | Custom [user action buttons](#action-buttons) for notifications |
|
||||
| `click` | - | *URL* | `https://example.com` | Website opened when notification is [clicked](#click-action) |
|
||||
| `attach` | - | *URL* | `https://example.com/file.jpg` | URL of an attachment, see [attach via URL](#attach-file-from-a-url) |
|
||||
| `markdown` | - | *bool* | `true` | Set to true if the `message` is Markdown-formatted |
|
||||
| `icon` | - | *string* | `https://example.com/icon.png` | URL to use as notification [icon](#icons) |
|
||||
| `filename` | - | *string* | `file.jpg` | File name of the attachment |
|
||||
| `delay` | - | *string* | `30min`, `9am` | Timestamp or duration for delayed delivery |
|
||||
| `email` | - | *e-mail address* | `phil@example.com` | E-mail address for e-mail notifications |
|
||||
| `call` | - | *phone number or 'yes'* | `+1222334444` or `yes` | Phone number to use for [voice call](#phone-calls) |
|
||||
| Field | Required | Type | Example | Description |
|
||||
|---------------|----------|----------------------------------|-------------------------------------------|-------------------------------------------------------------------------------------------|
|
||||
| `topic` | ✔️ | *string* | `topic1` | Target topic name |
|
||||
| `message` | - | *string* | `Some message` | Message body; set to `triggered` if empty or not passed |
|
||||
| `title` | - | *string* | `Some title` | Message [title](#message-title) |
|
||||
| `tags` | - | *string array* | `["tag1","tag2"]` | List of [tags](#tags-emojis) that may or not map to emojis |
|
||||
| `priority` | - | *int (one of: 1, 2, 3, 4, or 5)* | `4` | Message [priority](#message-priority) with 1=min, 3=default and 5=max |
|
||||
| `actions` | - | *JSON array* | *(see [action buttons](#action-buttons))* | Custom [user action buttons](#action-buttons) for notifications |
|
||||
| `click` | - | *URL* | `https://example.com` | Website opened when notification is [clicked](#click-action) |
|
||||
| `attach` | - | *URL* | `https://example.com/file.jpg` | URL of an attachment, see [attach via URL](#attach-file-from-a-url) |
|
||||
| `markdown` | - | *bool* | `true` | Set to true if the `message` is Markdown-formatted |
|
||||
| `icon` | - | *string* | `https://example.com/icon.png` | URL to use as notification [icon](#icons) |
|
||||
| `filename` | - | *string* | `file.jpg` | File name of the attachment |
|
||||
| `delay` | - | *string* | `30min`, `9am` | Timestamp or duration for delayed delivery |
|
||||
| `email` | - | *e-mail address* | `phil@example.com` | E-mail address for e-mail notifications |
|
||||
| `call` | - | *phone number or 'yes'* | `+1222334444` or `yes` | Phone number to use for [voice call](#phone-calls) |
|
||||
| `sequence_id` | - | *string* | `my-sequence-123` | Sequence ID for [updating/deleting notifications](#updating-deleting-notifications) |
|
||||
|
||||
## Action buttons
|
||||
_Supported on:_ :material-android: :material-apple: :material-firefox:
|
||||
@@ -2694,6 +2695,134 @@ Here's an example that will open Reddit when the notification is clicked:
|
||||
]));
|
||||
```
|
||||
|
||||
## Updating + deleting notifications
|
||||
_Supported on:_ :material-android: :material-firefox:
|
||||
|
||||
You can update, clear (mark as read), 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.
|
||||
|
||||
The key concept is the **sequence ID** (`sequence_id` or `sid`): notifications with the same sequence ID are treated as
|
||||
belonging to the same sequence, and clients will update/replace the notification accordingly.
|
||||
|
||||
### 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:
|
||||
|
||||
1. **Use the message ID**: First publish without a sequence ID, then use the returned message `id` as the sequence ID for updates
|
||||
2. **Use a custom sequence ID**: Publish directly to `/<topic>/<sequence_id>` with your own identifier
|
||||
|
||||
=== "Using the message ID"
|
||||
```bash
|
||||
# First, publish a message and capture the message ID
|
||||
$ curl -d "Downloading file..." ntfy.sh/mytopic
|
||||
{"id":"xE73Iyuabi","time":1673542291,...}
|
||||
|
||||
# Then use the message ID to update it
|
||||
$ curl -d "Download complete!" ntfy.sh/mytopic/xE73Iyuabi
|
||||
```
|
||||
|
||||
=== "Using a custom sequence ID"
|
||||
```bash
|
||||
# Publish with a custom sequence ID
|
||||
$ curl -d "Downloading file..." ntfy.sh/mytopic/my-download-123
|
||||
|
||||
# Update using the same sequence ID
|
||||
$ curl -d "Download complete!" ntfy.sh/mytopic/my-download-123
|
||||
```
|
||||
|
||||
=== "Using the X-Sequence-ID header"
|
||||
```bash
|
||||
# Publish with a sequence ID via header
|
||||
$ curl -H "X-Sequence-ID: my-download-123" -d "Downloading..." ntfy.sh/mytopic
|
||||
|
||||
# Update using the same sequence ID
|
||||
$ curl -H "X-Sequence-ID: my-download-123" -d "Done!" ntfy.sh/mytopic
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### Clearing notifications
|
||||
To clear a notification (mark it as read and dismiss it from the notification drawer), send a PUT request to
|
||||
`/<topic>/<sequence_id>/clear` (or `/<topic>/<sequence_id>/read` as an alias):
|
||||
|
||||
=== "Command line (curl)"
|
||||
```bash
|
||||
curl -X PUT ntfy.sh/mytopic/my-download-123/clear
|
||||
```
|
||||
|
||||
=== "HTTP"
|
||||
```http
|
||||
PUT /mytopic/my-download-123/clear HTTP/1.1
|
||||
Host: ntfy.sh
|
||||
```
|
||||
|
||||
This publishes a `message_clear` event, which tells clients to:
|
||||
|
||||
- Mark the notification as read in the app
|
||||
- Dismiss the browser/Android notification
|
||||
|
||||
### Deleting notifications
|
||||
To delete a notification entirely, send a DELETE request to `/<topic>/<sequence_id>`:
|
||||
|
||||
=== "Command line (curl)"
|
||||
```bash
|
||||
curl -X DELETE ntfy.sh/mytopic/my-download-123
|
||||
```
|
||||
|
||||
=== "HTTP"
|
||||
```http
|
||||
DELETE /mytopic/my-download-123 HTTP/1.1
|
||||
Host: ntfy.sh
|
||||
```
|
||||
|
||||
This publishes a `message_delete` event, which tells clients to:
|
||||
|
||||
- Delete the notification from the database
|
||||
- Dismiss the browser/Android notification
|
||||
|
||||
!!! info
|
||||
Deleted sequences can be revived by publishing a new message with the same sequence ID. The notification will
|
||||
reappear as a new message.
|
||||
|
||||
### Full example
|
||||
Here's a complete example showing the lifecycle of a notification with updates, clearing, and deletion:
|
||||
|
||||
```bash
|
||||
# 1. Create a notification with a custom sequence ID
|
||||
$ curl -d "Starting backup..." ntfy.sh/mytopic/backup-2024
|
||||
|
||||
# 2. Update the notification with progress
|
||||
$ curl -d "Backup 50% complete..." ntfy.sh/mytopic/backup-2024
|
||||
|
||||
# 3. Update again when complete
|
||||
$ curl -d "Backup finished successfully!" ntfy.sh/mytopic/backup-2024
|
||||
|
||||
# 4. Clear the notification (dismiss from notification drawer)
|
||||
$ curl -X PUT ntfy.sh/mytopic/backup-2024/clear
|
||||
|
||||
# 5. Later, delete the notification entirely
|
||||
$ curl -X DELETE ntfy.sh/mytopic/backup-2024
|
||||
```
|
||||
|
||||
When polling the topic, you'll see the complete sequence of events:
|
||||
|
||||
```bash
|
||||
$ curl -s "ntfy.sh/mytopic/json?poll=1&since=all" | jq .
|
||||
```
|
||||
|
||||
```json
|
||||
{"id":"abc123","time":1673542291,"event":"message","topic":"mytopic","sequence_id":"backup-2024","message":"Starting backup..."}
|
||||
{"id":"def456","time":1673542295,"event":"message","topic":"mytopic","sequence_id":"backup-2024","message":"Backup 50% complete..."}
|
||||
{"id":"ghi789","time":1673542300,"event":"message","topic":"mytopic","sequence_id":"backup-2024","message":"Backup finished successfully!"}
|
||||
{"id":"jkl012","time":1673542305,"event":"message_clear","topic":"mytopic","sequence_id":"backup-2024"}
|
||||
{"id":"mno345","time":1673542400,"event":"message_delete","topic":"mytopic","sequence_id":"backup-2024"}
|
||||
```
|
||||
|
||||
Clients process these events in order, keeping only the latest state for each sequence ID.
|
||||
|
||||
## Attachments
|
||||
_Supported on:_ :material-android: :material-firefox:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user