# Send a message

The one call your tool uses to send a message: text, title, formatting, link and image.

A message is a single call: `POST /v1/push`. This page shows what you can put in it. In a channel, it is an alert or (with replies) your tool's answer. An app can also send such a message, and it arrives as a push.

**You need:** a packlet and its key in `PACKLETS_KEY`, see [Quickstart](https://packlets.app/en/docs/schnellstart.md).

## Text and title

Only `text` is required. With `title`, the message gets a heading.

```bash
curl https://api.packlets.app/v1/push \
  -H "Authorization: Bearer $PACKLETS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Backup", "text": "Last night'"'"'s backup is done."}'
```

```python
import os, requests

res = requests.post("https://api.packlets.app/v1/push", timeout=10,
                    headers={"Authorization": f"Bearer {os.environ['PACKLETS_KEY']}"},
                    json={"title": "Backup", "text": "Last night's backup is done."})
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.PACKLETS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Backup", text: "Last night's backup is done." }),
});
if (!res.ok) throw new Error(`Packlets ${res.status}: ${await res.text()}`);
const { message_id } = (await res.json()) as { message_id: string };
```

- `text` can be up to 10,000 characters long. The app collapses long texts and shows "Read more".
- `title` can be up to 80 characters long. Without a title, the push shows only the name of your packlet.

The key decides which channel the message lands in. There is no channel field.

## Formatting

Simple formatting is allowed in `text`. The app renders it; in the push on the lock screen, the characters are removed.

| Syntax | Result |
|---|---|
| `## Heading` | Heading |
| `- Item` or `• Item` | List |
| `1. Item` | Numbered list |
| `**bold**` | Bold |
| Blank line | New paragraph |

Other Markdown such as links, italics, tables, or code is not converted and appears exactly as you write it.

In JSON, you write a line break as `\n`, so a blank line is `\n\n`:

```json
{
  "title": "Daily report",
  "text": "## Today\n- 3 deploys, all **successful**\n- Backup finished at 3:00\n\n## Open\n1. Certificate for shop.example.com expires in 9 days\n2. 2 orders not yet shipped"
}
```

## Link and image

| Field | What the app shows |
|---|---|
| `url` | The message's link. Without an image, the app shows a line with the address; tapping opens it. |
| `image` | The image above the text. Together with `url`, tapping the image opens the link. |

```json
{
  "title": "New match: Road bike, €450",
  "text": "Just listed, 3 km away.",
  "url": "https://example.com/listing/1042",
  "image": "https://example.com/listing/1042/image.jpg"
}
```

Both must be public `https` addresses. Packlets does not upload the image; the phone fetches it directly from that address. If `url` points to a video (YouTube, Vimeo, or a video file), a play icon appears on the image.

## The response

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

Status `200` means: the message is saved and appears in the channel. You only need the `message_id` if the message has [buttons](https://packlets.app/en/docs/knoepfe.md). It then comes back in the webhook.

Any other status is an error, and the message was not saved. The cause is in the `error` field, see [Error codes](https://packlets.app/en/docs/fehler.md).

## What's next

- Let people respond to a message: [Buttons](https://packlets.app/en/docs/knoepfe.md).
- Put toggles, charts, or tables in the message: [Elements in messages](https://packlets.app/en/docs/nachrichten-elemente.md).
- Control whether and how loudly the push arrives: [Push, sound, and quiet hours](https://packlets.app/en/docs/push.md).
- All fields at a glance: [POST /v1/push](https://packlets.app/en/docs/api-push.md).
