Reference
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 under the bell. Instead of the packlet's key, the key of a service works too.
The guide for this: Send a message.
Request
HTTP
POST https://api.packlets.app/v1/push
Authorization: Bearer <PACKLETS_KEY>
Content-Type: application/jsonFields
| Field | Type | Required | Meaning |
|---|---|---|---|
text | text, 1 to 10,000 characters | yes | The message. Simple 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 below the message. |
elements | list, up to 12 items | no | Elements in the message. |
priority | normal, high or silent | no | Default normal. See Push, sound and quiet hours. |
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.