Reference

POST /v1/push

Send a message: all fields, response and errors.

Open as Markdown

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/json

Fields

FieldTypeRequiredMeaning
texttext, 1 to 10,000 charactersyesThe message. Simple formatting is allowed.
titletext, up to 80 charactersnoHeading.
urlhttps address, up to 2,048 charactersnoThe message's link.
imagehttps address, up to 2,048 charactersnoImage above the text.
buttonslist, up to 3 itemsnoButtons below the message.
elementslist, up to 12 itemsnoElements in the message.
prioritynormal, high or silentnoDefault normal. See Push, sound and quiet hours.

Button fields

FieldTypeRequiredMeaning
idtext, 1 to 64 charactersyesYour identifier, unique per message. Comes back in the webhook as button_id.
labeltext, 1 to 40 charactersyesLabel.
urlhttps addressnoWith 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" }
FieldMeaning
message_idThe message's identifier. It comes back in webhook events for this message.
warningsOnly 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

StatuserrorWhen
400invalid_bodyA field is missing or doesn't fit. details names the field and the reason.
401missing_key, invalid_keyKey is missing or wrong.
429rate_limitedMore 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.