# Ohne Code: ntfy

Samy versteht die Aufrufe von ntfy: Server ist die Samy-Adresse, Topic dein Schlüssel.

[ntfy](https://ntfy.sh) ist ein beliebter Weg, Push-Nachrichten aus Skripten und Server-Tools zu schicken. Samy versteht dieselben Aufrufe: Viele Tools mit ntfy-Option schicken damit direkt an Samy. Server ist die Samy-Adresse, Topic der Schlüssel deines Packlets.

Du schreibst dafür keinen Code. Einen ntfy-Server oder die ntfy-App brauchst du nicht.

## In der App verbinden

Tipp beim Verbinden auf **Integrationen** und wähle **ntfy**. Name und Tier sind schon ausgefüllt. Danach zeigt Samy **Server** und **Topic** zum Kopieren; die trägst du in deinem Tool bei ntfy ein.

## Server und Topic

| Feld im Tool | Wert |
|---|---|
| Server (Server-URL) | `https://api.packlets.app` |
| Topic | `<SAMY_KEY>` |

Fragt das Tool nach einer einzigen Adresse, ist es beides zusammen: `https://api.packlets.app/<SAMY_KEY>`.

> Das Topic ist hier dein Schlüssel. Behandle es wie ein Passwort. Erzeugst du in der App einen neuen Schlüssel, gilt das alte Topic sofort nicht mehr.

Hat das Tool ein eigenes Feld für ein Access-Token oder ein Passwort, kannst du den Schlüssel auch dort eintragen und ein beliebiges Topic wählen, zum Beispiel `backup`. Samy nimmt den Schlüssel dann aus `Authorization: Bearer …` oder aus dem Passwort der Basic-Anmeldung.

## Wo das funktioniert

| Bereich | Tools |
|---|---|
| Smart Home | Home Assistant, Node-RED, ioBroker |
| Überwachung | Uptime Kuma, Healthchecks.io, Gatus, Changedetection.io, Beszel |
| Server | Watchtower, Proxmox, Unraid, Diun, Backrest, borgmatic |
| Medien | Sonarr, Radarr, Jellyseerr |
| Alles mit Apprise | Apprise-Adressen `ntfys://…` (ohne eigenen Pfad im Server) |
| Eigene Skripte | Alles, was schon an ntfy schickt: Server tauschen, fertig |

## Schnell testen

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

Mit Titel, Priorität und Link:

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

Samy antwortet wie ntfy mit JSON (`id`, `time`, `event`, `message`). Im Packlet-Protokoll steht der Aufruf mit „ntfy:“ davor.

## Die drei Wege

| Weg | Beispiel |
|---|---|
| Text als Body, Angaben in Headern | `POST https://api.packlets.app/<SAMY_KEY>` (auch `PUT`) |
| Alles in der Adresse | `GET https://api.packlets.app/<SAMY_KEY>/publish?message=Hallo&title=Test` (auch `/send`, `/trigger`) |
| JSON an den Server | `POST https://api.packlets.app/` mit `{"topic":"<SAMY_KEY>","message":"Hallo"}` |

Wie bei ntfy ist beim ersten Weg der Body immer die Nachricht, auch wenn er wie JSON aussieht.

## Was Samy übernimmt

Header gibt es in allen Schreibweisen von ntfy (`Title`, `X-Title`, `t`); dieselben Namen gehen als Parameter in der Adresse.

| ntfy | In Samy |
|---|---|
| Body oder `Message` | Text der Nachricht. Leer: „Ausgelöst“. |
| `Title` | Titel |
| `Priority` `1`–`2` (`min`, `low`) | [Priorität](https://packlets.app/docs/push.md) `silent` |
| `Priority` `3` (`default`) | `normal` |
| `Priority` `4`–`5` (`high`, `urgent`, `max`) | `high` |
| `Tags` wie `warning`, `tada`, `white_check_mark` | Emoji vor dem Titel (sonst vor dem Text). Tags ohne Emoji fallen weg. |
| `Click` | Link der Nachricht |
| `Attach` mit Bild-Link (`.png`, `.jpg`, …) | Bild der Nachricht; andere Links werden zum Link |
| `Actions` mit `view` | bis zu 3 [Knöpfe](https://packlets.app/docs/knoepfe.md), die den Link öffnen |
| `Markdown: yes` | Formatierung wie in Samy, Links `[Text](url)` werden zum Link |
| Umlaute in Headern (RFC 2047 oder UTF-8) | richtig |

## Antworten

| Status | Antwort | Bedeutung |
|---|---|---|
| `200` | JSON mit `id` und `event: "message"` | Gespeichert, der Push ist unterwegs. |
| `400` | JSON mit `code` und `error` | Keine gültige Nachricht, kein JSON beim JSON-Weg oder eine Datei als Anhang. |
| `401` | JSON mit `invalid_key` | Schlüssel falsch oder Packlet entfernt. |
| `404` | JSON mit `code` `40401` | Das Topic ist kein Schlüssel und es gibt auch keinen im Token oder Passwort. |
| `429` | JSON mit `rate_limited` | Zu viele Aufrufe. Es gilt dasselbe [Limit](https://packlets.app/docs/api.md#rate-limit) wie bei `POST /v1/push`. |

## Grenzen

- Samy nimmt nur Nachrichten an. Abonnieren (`/json`, `/sse`, `/ws`) gibt es nicht; die Nachrichten landen in der Samy-App.
- Dateien als Anhang hochladen geht nicht. Bilder gehen als Link mit `Attach`.
- `http`- und `broadcast`-Aktionen, `Delay`, `Email`, `Call` und `Icon` lässt Samy weg.