# POST /v1/push

Eine Nachricht schicken: alle Felder, Antwort und Fehler.

Schickt eine Nachricht in den Kanal des Packlets. Geht für jede Kanal-Art: Im Kanal ist es eine Meldung oder die Antwort deines Tools, bei einer App eine Benachrichtigung.

Die Anleitung dazu: [Nachricht senden](https://packlets.app/docs/senden.md).

## Aufruf

```http
POST https://api.packlets.app/v1/push
Authorization: Bearer <SAMY_KEY>
Content-Type: application/json
```

## Felder

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `text` | Text, 1 bis 10.000 Zeichen | ja | Die Nachricht. Erlaubt ist einfache [Formatierung](https://packlets.app/docs/senden.md#formatierung). |
| `title` | Text, bis 80 Zeichen | nein | Überschrift. |
| `url` | `https`-Adresse, bis 2.048 Zeichen | nein | Link der Nachricht. |
| `image` | `https`-Adresse, bis 2.048 Zeichen | nein | Bild über dem Text. |
| `buttons` | Liste, bis 3 Einträge | nein | [Knöpfe](https://packlets.app/docs/knoepfe.md) unter der Nachricht. |
| `elements` | Liste, bis 12 Einträge | nein | [Elemente](https://packlets.app/docs/elemente.md) in der Nachricht. |
| `priority` | `normal`, `high` oder `silent` | nein | Standard `normal`. Siehe [Push, Ton und Ruhezeit](https://packlets.app/docs/push.md). |

### Felder eines Knopfs

| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
| `id` | Text, 1 bis 64 Zeichen | ja | Deine Kennung, pro Nachricht eindeutig. Kommt im Webhook als `button_id` zurück. |
| `label` | Text, 1 bis 40 Zeichen | ja | Beschriftung. |
| `url` | `https`-Adresse | nein | Mit `url` öffnet der Knopf einen Link, ohne meldet er den Tipp an deinen Webhook. |

## Beispiel

```json
{
  "title": "Deploy fehlgeschlagen",
  "text": "**shop-api** auf main: Tests rot in `checkout.test.ts`.",
  "url": "https://ci.example.com/runs/4711",
  "priority": "high",
  "buttons": [
    { "id": "retry", "label": "Erneut starten" },
    { "id": "log", "label": "Log öffnen", "url": "https://ci.example.com/runs/4711/log" }
  ]
}
```

## Antwort

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

| Feld | Bedeutung |
|---|---|
| `message_id` | Kennung der Nachricht. Sie kommt in Webhook-Ereignissen zu dieser Nachricht wieder. |
| `warnings` | Nur wenn Samy die Größe eines Elements angepasst hat: Liste mit je einem Satz pro Änderung. |

Status `200` heißt: Die Nachricht ist gespeichert und steht im Kanal. Das gilt auch, wenn der Push nicht zugestellt wird, zum Beispiel in der Ruhezeit.

Der erste erfolgreiche Aufruf verbindet das Packlet: Die App zeigt „Verbunden!“.

## Fehler

| Status | `error` | Wann |
|---|---|---|
| 400 | `invalid_body` | Ein Feld fehlt oder passt nicht. `details` nennt Feld und Grund. |
| 401 | `missing_key`, `invalid_key` | Schlüssel fehlt oder ist falsch. |
| 429 | `rate_limited` | Mehr als 60 Aufrufe in einer Minute. |

Was du jeweils tun kannst, steht unter [Fehlercodes](https://packlets.app/docs/fehler.md).