# Buttons

Buttons under a message open links or answer your tool with a tap.

Up to three buttons can sit below a message. A button either opens a link, or it tells your tool that you tapped it.

**You need:** [Send a message](https://packlets.app/en/docs/senden.md). For action buttons, you also need a [webhook](https://packlets.app/en/docs/webhook.md).

## Add buttons

Buttons go in the `buttons` field. Each needs an `id` and a `label`:

```bash
curl https://api.packlets.app/v1/push \
  -H "Authorization: Bearer $PACKLETS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New invoice: Hosting GmbH",
    "text": "**€189.00**, due Nov 20. Approve?",
    "buttons": [
      {"id": "approve", "label": "Approve"},
      {"id": "pdf", "label": "Open PDF", "url": "https://example.com/invoices/2026-118.pdf"}
    ]
  }'
```

```python
import os, requests

requests.post("https://api.packlets.app/v1/push", timeout=10,
              headers={"Authorization": f"Bearer {os.environ['PACKLETS_KEY']}"},
              json={"title": "New invoice: Hosting GmbH",
                    "text": "**€189.00**, due Nov 20. Approve?",
                    "buttons": [
                        {"id": "approve", "label": "Approve"},
                        {"id": "pdf", "label": "Open PDF", "url": "https://example.com/invoices/2026-118.pdf"},
                    ]}).raise_for_status()
```

```typescript
await fetch("https://api.packlets.app/v1/push", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PACKLETS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "New invoice: Hosting GmbH",
    text: "**€189.00**, due Nov 20. Approve?",
    buttons: [
      { id: "approve", label: "Approve" },
      { id: "pdf", label: "Open PDF", url: "https://example.com/invoices/2026-118.pdf" },
    ],
  }),
});
```

| Field | Meaning |
|---|---|
| `id` | Your identifier for the button, up to 64 characters, unique per message. |
| `label` | The label, up to 40 characters. |
| `url` | Makes the button a link button. |

## Two kinds

Whether a button opens a link or triggers an action is decided solely by the `url` field.

| | Link button | Action button |
|---|---|---|
| Recognizable by | has a `url` | has no `url` |
| When tapped | The address opens on the phone. | Packlets reports the tap to your webhook. |
| Your tool finds out | no | yes |
| How often | any number of times | once per message |

In the example above, "Approve" is an action button and "Open PDF" is a link button.

## What happens after the tap

When you tap an action button, two things happen:

1. The message immediately shows which button you chose. The action buttons of this message are now done, and a second tap is not possible.
2. Packlets sends the `button` event to your 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` is the `id` you assigned. `message_id` is the value you got as the response when sending. Keep it if your tool needs to know which message the tap belongs to.

How your tool receives the event is covered in [Set up a webhook](https://packlets.app/en/docs/webhook.md).

> **Note:** If your packlet has no webhook URL, the app still shows the tap. But your tool doesn't learn about it.

## When to use elements instead

Buttons are for a one-time answer. If you need a toggle, an input, or a button that can be pressed more than once, use [elements in messages](https://packlets.app/en/docs/nachrichten-elemente.md).
