# Aktionsbuttons

Eine Push-Benachrichtigung kann bis zu drei Buttons enthalten. Statt eine Meldung zu lesen und dann den Laptop aufzuklappen, um etwas dagegen zu tun, handelst du direkt vom Sperrbildschirm aus: Lauf öffnen, Neustart auslösen, Code kopieren.

## Die drei Typen

| Typ | Was der Button macht | `value` enthält |
|------|----------------------|---------------|
| `view` | Öffnet eine URL | Die URL, z. B. `https://status.example.com` |
| `http` | Sendet im Hintergrund einen HTTP-Request | Ein JSON-String: `{"url":"…","method":"POST","headers":{…},"body":"…"}` |
| `copy` | Kopiert Text in die Zwischenablage | Der wörtliche Text zum Kopieren |

Bei `http` ist nur `url` erforderlich — `method` ist standardmäßig `GET`. Ist `body` gesetzt und kein Content-Type angegeben, wird automatisch `Content-Type: application/json` ergänzt.

`http` und `copy` laufen, ohne die App zu öffnen, auch wenn sie geschlossen ist. `view` holt die App oder den Browser in den Vordergrund.

## Wo Buttons erscheinen

Buttons werden in der Systembenachrichtigung auf iOS und Android angezeigt, egal ob die App geöffnet, im Hintergrund oder geschlossen ist. Außerdem sind sie in der Nachricht selbst enthalten. Das ist wichtig: Wischst du das Banner weg, sind die Buttons trotzdem noch da, wenn du die Nachricht später öffnest.

- **Beschriftungen** werden auf beiden Plattformen genau so angezeigt, wie du sie sendest. Kann iOS die individuellen Buttons nicht rechtzeitig vorbereiten, greift es auf eine generische Beschriftung pro Typ zurück — **Öffnen**, **Ausführen**, **Kopieren** — und die Buttons funktionieren trotzdem.
- **Sperrbildschirm.** `http` und `copy` laufen vom Sperrbildschirm aus, ohne dass du entsperren musst. `view` öffnet die App oder den Browser, daher fragt das Handy zuerst nach dem Entsperren. Auf Android werden die Buttons auf dem Sperrbildschirm nur angezeigt, wenn dieser so eingestellt ist, dass Benachrichtigungsinhalte gezeigt werden.
- **Fehlgeschlagene Requests.** Schlägt ein `http`-Request fehl (ein Status außerhalb 2xx/3xx oder ein Netzwerkfehler), erscheint eine Benachrichtigung mit einem **Wiederholen**-Button. Ein Request, der deinen Server möglicherweise erreicht hat, wird nie automatisch wiederholt.
- **App-Version.** Systembenachrichtigungs-Buttons benötigen die Pocket Alert App ab Version 2.0.1. Ältere Versionen zeigen die Buttons nur innerhalb der Nachricht an.

## Freigabe-Workflows

Zwei `http`-Buttons — **Genehmigen** und **Ablehnen** — machen aus einer Benachrichtigung ein Ein-Tipp-Bedienfeld. Das Muster funktioniert für alles, was auf eine Entscheidung eines Menschen wartet:

- Eine Deployment-Pipeline, die auf manuelle Freigabe wartet
- Ein LLM-Agent, der Zustimmung braucht, bevor er Geld ausgibt oder Produktivsysteme anfasst
- Eine Rückerstattung über einem Schwellenwert
- Eine Tür, ein Tor, ein Licht, eine Garage

Der Request geht direkt vom Handy an deinen Endpunkt. Pocket Alert leitet ihn nicht weiter und sieht den Response-Body nicht.

> **Warning: Idempotenz liegt bei dir**
>
> Tippst du denselben `http`-Button zweimal, wird der Request auch zweimal gesendet — Wiederholungen blockieren wir nicht. Ist doppeltes Auslösen teuer, mach den Endpunkt idempotent.

## Buttons aus Webhooks

Webhooks können ein Aktionsvorlage mit `%path%`-Platzhaltern enthalten, die aus dem eingehenden Payload gefüllt werden. Eine Sentry-Meldung kann so mit einem funktionierenden **Issue öffnen**-Button ankommen, der auf genau dieses Issue zeigt; ein Stripe-Event mit einem **Zahlung ansehen**-Button für diese Belastung.

Eingesetzte Werte werden JSON-escaped, bevor die Vorlage geparst wird. Ein Payload-Feld mit Anführungszeichen kann so nicht ausbrechen und die URL umschreiben. Ergibt ein Button etwas Ungültiges, zum Beispiel einen **Runbook**-Button, wenn die Meldung keine Runbook-URL hat, wird nur dieser Button verworfen; die übrigen Buttons und die Nachricht werden trotzdem zugestellt. Ein fehlerhafter Button kostet dich nie die Meldung.

Du kannst die Vorlage in der Konsole beim Erstellen oder Bearbeiten eines Webhooks setzen oder über die [Webhooks-API](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

## Limits und Validierung

- Maximal **3** Buttons pro Nachricht; sie werden in der Reihenfolge angezeigt, in der du sie sendest.
- Das `actions`-Array darf im JSON-kodierten Zustand höchstens **2048 Bytes** groß sein. Es wird mit der Push-Benachrichtigung übertragen, die auf 4 KB begrenzt ist, daher wird eine lange `message` gekürzt, um Platz zu schaffen.
- `view` und `http` benötigen eine gültige `http(s)`-URL. Alles andere liefert `400` an der API zurück; in einer Webhook-Vorlage wird der ungültige Button verworfen.
- Unbekannte `type`-Werte liefern `400`.

> **Warning: Bezahlfunktion**
>
> Aktionsbuttons werden in kostenlosen Tarifen serverseitig aus Nachrichten entfernt. Die Nachricht selbst wird normal zugestellt.

## Verwandte Seiten

- [Nachricht erstellen](https://info.pocketalert.app/api/messages/create.md) — das `actions`-Array und die vollständige Request-Referenz
- [Prioritätsstufen](https://info.pocketalert.app/features/priority-levels.md) — wie laut die Meldung ankommt
- [Webhook-Einstellungen](https://info.pocketalert.app/api/webhooks/settings.md) — Aktionsvorlagen für eingehende Webhooks
