# Knöpfe

Mit Knöpfen unter einer Nachricht öffnest du Links oder antwortest deinem Tool mit einem Tipp.

Unter einer Nachricht können bis zu drei Knöpfe stehen. Ein Knopf öffnet entweder einen Link, oder er meldet deinem Tool, dass du ihn getippt hast.

**Du brauchst:** [Nachricht senden](https://packlets.app/docs/senden.md). Für Aktions-Knöpfe zusätzlich einen [Webhook](https://packlets.app/docs/webhook.md).

## Knöpfe mitschicken

Knöpfe stehen im Feld `buttons`. Jeder braucht eine `id` und ein `label`:

```bash
curl https://api.packlets.app/v1/push \
  -H "Authorization: Bearer $SAMY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Neue Rechnung: Hosting GmbH",
    "text": "**189,00 €**, fällig am 20.11. Freigeben?",
    "buttons": [
      {"id": "approve", "label": "Freigeben"},
      {"id": "pdf", "label": "PDF öffnen", "url": "https://example.com/rechnungen/2026-118.pdf"}
    ]
  }'
```

```python
import os, requests

requests.post("https://api.packlets.app/v1/push", timeout=10,
              headers={"Authorization": f"Bearer {os.environ['SAMY_KEY']}"},
              json={"title": "Neue Rechnung: Hosting GmbH",
                    "text": "**189,00 €**, fällig am 20.11. Freigeben?",
                    "buttons": [
                        {"id": "approve", "label": "Freigeben"},
                        {"id": "pdf", "label": "PDF öffnen", "url": "https://example.com/rechnungen/2026-118.pdf"},
                    ]}).raise_for_status()
```

```typescript
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: "Neue Rechnung: Hosting GmbH",
    text: "**189,00 €**, fällig am 20.11. Freigeben?",
    buttons: [
      { id: "approve", label: "Freigeben" },
      { id: "pdf", label: "PDF öffnen", url: "https://example.com/rechnungen/2026-118.pdf" },
    ],
  }),
});
```

| Feld | Bedeutung |
|---|---|
| `id` | Deine Kennung für den Knopf, bis 64 Zeichen, pro Nachricht eindeutig. |
| `label` | Die Beschriftung, bis 40 Zeichen. |
| `url` | Macht den Knopf zum Link-Knopf. |

## Zwei Arten

Ob ein Knopf einen Link öffnet oder eine Aktion auslöst, entscheidet allein das Feld `url`.

| | Link-Knopf | Aktions-Knopf |
|---|---|---|
| Erkennbar an | hat `url` | hat keine `url` |
| Beim Tippen | Die Adresse öffnet sich auf dem Handy. | Samy meldet den Tipp an deinen Webhook. |
| Dein Tool erfährt es | nein | ja |
| Wie oft | beliebig oft | einmal pro Nachricht |

Im Beispiel oben ist „Freigeben“ ein Aktions-Knopf und „PDF öffnen“ ein Link-Knopf.

## Was nach dem Tipp passiert

Tippst du einen Aktions-Knopf, passieren zwei Dinge:

1. Die Nachricht zeigt sofort, welchen Knopf du gewählt hast. Die Aktions-Knöpfe dieser Nachricht sind damit erledigt, ein zweiter Tipp geht nicht.
2. Samy schickt das Ereignis `button` an deinen Webhook:

```json
{
  "type": "button",
  "packlet_id": "9d2f7c10-3a5b-4c8e-9f21-6b7d8e9f0a12",
  "message_id": "5b0c1a52-7c1e-4a43-9d0b-2f6f0c7d1e11",
  "button_id": "approve",
  "pressed_at": "2026-11-09T18:00:00.000Z"
}
```

`button_id` ist die `id`, die du vergeben hast. `message_id` ist der Wert, den du beim Senden als Antwort bekommen hast. Merk ihn dir, wenn dein Tool wissen muss, zu welcher Meldung der Tipp gehört.

Wie dein Tool das Ereignis empfängt, steht unter [Webhook einrichten](https://packlets.app/docs/webhook.md).

> **Hinweis:** Hat dein Packlet keine Webhook-URL, zeigt die App den Tipp trotzdem an. Dein Tool erfährt aber nichts davon.

## Wann lieber Elemente

Knöpfe sind für eine einmalige Antwort. Brauchst du einen Schalter, ein Eingabefeld oder einen Button, den man mehrmals drücken kann, nimm [Elemente in Nachrichten](https://packlets.app/docs/nachrichten-elemente.md).