# Nachricht senden

Der eine Aufruf, mit dem dein Tool eine Nachricht schickt: Text, Titel, Formatierung, Link und Bild.

Eine Nachricht ist ein einziger Aufruf: `POST /v1/push`. Diese Seite zeigt, was du hineinpacken kannst. Im Kanal ist es eine Meldung oder (mit Antworten) die Antwort deines Tools. Auch eine App kann so eine Nachricht schicken, sie kommt dann als Push.

**Du brauchst:** ein Packlet und seinen Schlüssel in `SAMY_KEY`, siehe [Schnellstart](https://packlets.app/docs/schnellstart.md).

## Text und Titel

Pflicht ist nur `text`. Mit `title` bekommt die Nachricht eine Überschrift.

```bash
curl https://api.packlets.app/v1/push \
  -H "Authorization: Bearer $SAMY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Backup", "text": "Backup von heute Nacht ist fertig."}'
```

```python
import os, requests

res = requests.post("https://api.packlets.app/v1/push", timeout=10,
                    headers={"Authorization": f"Bearer {os.environ['SAMY_KEY']}"},
                    json={"title": "Backup", "text": "Backup von heute Nacht ist fertig."})
res.raise_for_status()
print(res.json()["message_id"])
```

```typescript
const res = await fetch("https://api.packlets.app/v1/push", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SAMY_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Backup", text: "Backup von heute Nacht ist fertig." }),
});
if (!res.ok) throw new Error(`Samy ${res.status}: ${await res.text()}`);
const { message_id } = (await res.json()) as { message_id: string };
```

- `text` darf bis zu 10.000 Zeichen lang sein. Lange Texte klappt die App ein und zeigt „Weiterlesen“.
- `title` darf bis zu 80 Zeichen lang sein. Ohne Titel steht im Push nur der Name deines Packlets.

In welchem Kanal die Nachricht landet, bestimmt der Schlüssel. Eine Kanal-Angabe gibt es nicht.

## Formatierung

Im `text` ist einfache Formatierung erlaubt. Die App stellt sie dar, im Push auf dem Sperrbildschirm werden die Zeichen entfernt.

| Schreibweise | Ergebnis |
|---|---|
| `## Überschrift` | Überschrift |
| `- Punkt` oder `• Punkt` | Liste |
| `1. Punkt` | nummerierte Liste |
| `**fett**` | Fettdruck |
| Leerzeile | neuer Absatz |

Anderes Markdown wie Links, Kursiv, Tabellen oder Code wird nicht umgewandelt und erscheint so, wie du es schreibst.

In JSON schreibst du einen Zeilenumbruch als `\n`, eine Leerzeile also als `\n\n`:

```json
{
  "title": "Tagesbericht",
  "text": "## Heute\n- 3 Deploys, alle **erfolgreich**\n- Backup um 3:00 fertig\n\n## Offen\n1. Zertifikat für shop.example.de läuft in 9 Tagen ab\n2. 2 Bestellungen noch nicht versendet"
}
```

## Link und Bild

| Feld | Was die App zeigt |
|---|---|
| `url` | Der Link der Nachricht. Ohne Bild zeigt die App eine Zeile mit der Adresse; tippen öffnet sie. |
| `image` | Das Bild über dem Text. Zusammen mit `url` öffnet ein Tipp auf das Bild den Link. |

```json
{
  "title": "Neuer Treffer: Rennrad, 450 €",
  "text": "Gerade eingestellt, 3 km entfernt.",
  "url": "https://example.com/anzeige/1042",
  "image": "https://example.com/anzeige/1042/bild.jpg"
}
```

Beides müssen öffentliche `https`-Adressen sein. Samy lädt das Bild nicht hoch, das Handy holt es direkt von dieser Adresse. Zeigt `url` auf ein Video (YouTube, Vimeo oder eine Videodatei), liegt auf dem Bild ein Play-Symbol.

## Die Antwort

```json
{ "message_id": "5b0c1a52-7c1e-4a43-9d0b-2f6f0c7d1e11" }
```

Status `200` heißt: Die Nachricht ist gespeichert und steht im Kanal. Die `message_id` brauchst du nur, wenn die Nachricht [Knöpfe](https://packlets.app/docs/knoepfe.md) hat. Dann kommt sie im Webhook wieder.

Jeder andere Status ist ein Fehler, und die Nachricht wurde nicht gespeichert. Die Ursache steht im Feld `error`, siehe [Fehlercodes](https://packlets.app/docs/fehler.md).

## Wie es weitergeht

- Auf eine Nachricht antworten können: [Knöpfe](https://packlets.app/docs/knoepfe.md).
- Schalter, Diagramme oder Tabellen in die Nachricht setzen: [Elemente in Nachrichten](https://packlets.app/docs/nachrichten-elemente.md).
- Steuern, ob und wie laut der Push kommt: [Push, Ton und Ruhezeit](https://packlets.app/docs/push.md).
- Alle Felder auf einen Blick: [POST /v1/push](https://packlets.app/docs/api-push.md).