# No code: ntfy

Packlets understands ntfy calls: the server is the Packlets URL, the topic is your key.

[ntfy](https://ntfy.sh) is a popular way to send push notifications from scripts and server tools. Packlets understands the same calls: many tools with an ntfy option can send straight to Packlets. The server is the Packlets address, the topic is the key of your packlet.

You don't write any code for this. You don't need an ntfy server or the ntfy app.

## Connect in the app

When connecting, tap **Integrations** and choose **ntfy**. Name and animal are already filled in. Packlets then shows **Server** and **Topic** to copy; you enter them in your tool's ntfy setting.

## Server and topic

| Field in the tool | Value |
|---|---|
| Server (server URL) | `https://api.packlets.app` |
| Topic | `<PACKLETS_KEY>` |

If the tool asks for a single address, it's both together: `https://api.packlets.app/<PACKLETS_KEY>`.

> The topic is your key here. Treat it like a password. If you create a new key in the app, the old topic stops working immediately.

If the tool has a field of its own for an access token or a password, you can enter the key there instead and pick any topic, for example `backup`. Packlets then takes the key from `Authorization: Bearer …` or from the password of the Basic login.

## Where this works

| Area | Tools |
|---|---|
| Smart home | Home Assistant, Node-RED, ioBroker |
| Monitoring | Uptime Kuma, Healthchecks.io, Gatus, Changedetection.io, Beszel |
| Servers | Watchtower, Proxmox, Unraid, Diun, Backrest, borgmatic |
| Media | Sonarr, Radarr, Jellyseerr |
| Anything with Apprise | Apprise addresses `ntfys://…` (without a path of its own in the server) |
| Your own scripts | Anything that already sends to ntfy: swap the server, done |

## Quick test

```bash
curl -d "Backup done 🎉" https://api.packlets.app/<PACKLETS_KEY>
```

With title, priority and link:

```bash
curl https://api.packlets.app/<PACKLETS_KEY> \
  -H "Title: NAS" \
  -H "Priority: high" \
  -H "Tags: warning" \
  -H "Click: https://nas.example.com" \
  -d "Disk 95% full"
```

Packlets answers like ntfy with JSON (`id`, `time`, `event`, `message`). In the packlet's activity log, the call shows up with "ntfy:" in front.

## The three ways

| Way | Example |
|---|---|
| Text as body, details in headers | `POST https://api.packlets.app/<PACKLETS_KEY>` (also `PUT`) |
| Everything in the address | `GET https://api.packlets.app/<PACKLETS_KEY>/publish?message=Hello&title=Test` (also `/send`, `/trigger`) |
| JSON to the server | `POST https://api.packlets.app/` with `{"topic":"<PACKLETS_KEY>","message":"Hello"}` |

As with ntfy, with the first way the body is always the message, even if it looks like JSON.

## What Packlets picks up

Headers work in all of ntfy's spellings (`Title`, `X-Title`, `t`); the same names work as parameters in the address.

| ntfy | In Packlets |
|---|---|
| Body or `Message` | Message text. Empty: "Triggered", or "Ausgelöst" with the header `Accept-Language: de`. |
| `Title` | Title |
| `Priority` `1`–`2` (`min`, `low`) | [Priority](https://packlets.app/en/docs/push.md) `silent` |
| `Priority` `3` (`default`) | `normal` |
| `Priority` `4`–`5` (`high`, `urgent`, `max`) | `high` |
| `Tags` like `warning`, `tada`, `white_check_mark` | Emoji before the title (otherwise before the text). Tags without an emoji are dropped. |
| `Click` | Link of the message |
| `Attach` with an image link (`.png`, `.jpg`, …) | Image of the message; other links become the link |
| `Actions` with `view` | Up to 3 [buttons](https://packlets.app/en/docs/knoepfe.md) that open the link |
| `Markdown: yes` | Formatting as in Packlets, links `[text](url)` become the link |
| Umlauts in headers (RFC 2047 or UTF-8) | handled correctly |

## Responses

| Status | Response | Meaning |
|---|---|---|
| `200` | JSON with `id` and `event: "message"` | Saved, the push is on its way. |
| `400` | JSON with `code` and `error` | Not a valid message, no JSON on the JSON way, or a file as an attachment. |
| `401` | JSON with `invalid_key` | Key wrong or packlet removed. |
| `404` | JSON with `code` `40401` | The topic is not a key, and there is none in the token or password either. |
| `429` | JSON with `rate_limited` | Too many calls. The same [limit](https://packlets.app/en/docs/api.md#rate-limit) applies as for `POST /v1/push`. |

## Limits

- Packlets only accepts messages. Subscribing (`/json`, `/sse`, `/ws`) isn't available; messages land in the Packlets app.
- Uploading files as attachments doesn't work. Images work as a link with `Attach`.
- Packlets leaves out `http` and `broadcast` actions, `Delay`, `Email`, `Call` and `Icon`.
