# POST /v1/push

Send a message: all fields, response and errors.

Sends a message to the packlet's channel. It works for every channel type: in a channel it's an alert or your tool's reply, for an app it's a [notification](https://packlets.app/en/docs/apps.md#6-send-notifications) under the bell. Instead of the packlet's key, the key of a [service](https://packlets.app/en/docs/dienste.md) works too.

The guide for this: [Send a message](https://packlets.app/en/docs/senden.md).

## Request

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

## Fields

| Field | Type | Required | Meaning |
|---|---|---|---|
| `text` | text, 1 to 10,000 characters | yes | The message. Simple [formatting](https://packlets.app/en/docs/senden.md#formatting) is allowed. |
| `title` | text, up to 80 characters | no | Heading. |
| `url` | `https` address, up to 2,048 characters | no | The message's link. |
| `image` | `https` address, up to 2,048 characters | no | Image above the text. |
| `buttons` | list, up to 3 items | no | [Buttons](https://packlets.app/en/docs/knoepfe.md) below the message. |
| `elements` | list, up to 12 items | no | [Elements](https://packlets.app/en/docs/elemente.md) in the message. |
| `priority` | `normal`, `high` or `silent` | no | Default `normal`. See [Push, sound and quiet hours](https://packlets.app/en/docs/push.md). |

### Button fields

| Field | Type | Required | Meaning |
|---|---|---|---|
| `id` | text, 1 to 64 characters | yes | Your identifier, unique per message. Comes back in the webhook as `button_id`. |
| `label` | text, 1 to 40 characters | yes | Label. |
| `url` | `https` address | no | With `url` the button opens a link; without it, the button reports the tap to your webhook. |

## Example

```json
{
  "title": "Deploy failed",
  "text": "**shop-api** on main: tests red in `checkout.test.ts`.",
  "url": "https://ci.example.com/runs/4711",
  "priority": "high",
  "buttons": [
    { "id": "retry", "label": "Run again" },
    { "id": "log", "label": "Open log", "url": "https://ci.example.com/runs/4711/log" }
  ]
}
```

## Response

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

| Field | Meaning |
|---|---|
| `message_id` | The message's identifier. It comes back in webhook events for this message. |
| `warnings` | Only if Packlets adjusted the size of an element: a list with one sentence per change. |

Status `200` means: the message is saved and appears in the channel. This is also true if the push isn't delivered, for example during quiet hours.

The first successful call connects the packlet: the app shows "Connected!".

## Errors

| Status | `error` | When |
|---|---|---|
| 400 | `invalid_body` | A field is missing or doesn't fit. `details` names the field and the reason. |
| 401 | `missing_key`, `invalid_key` | Key is missing or wrong. |
| 429 | `rate_limited` | More than 60 calls in a minute for the packlet, or more than 300 for the account. |

What you can do in each case is covered under [Error codes](https://packlets.app/en/docs/fehler.md).
