Critical notifications

Every notification has one of five priorities. Set it with priority, or let it default to the Source’s own.

Priority	What it does
silent	Goes to the inbox without a notification on screen.
quiet	Shows a notification with no sound.
normal	A standard notification. Arrives silently during quiet hours.
important	Time Sensitive: it can break through a Focus.
critical	Repeats until it is acknowledged, canceled or expires.

Send a Critical notification

curl https://api.pocketbell.dev/v1/messages \
  -H "Authorization: Bearer pb_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: api-2-down-2026-09-28T02:14" \
  -d '{"title": "api-2 is down", "message": "Health check failed 3 times",
       "priority": "critical", "retry": 300, "expire": 3600}'

• retry is the time between repeats, in seconds: 30 to 3600, 300 by default.
• expire is when repeats stop, in seconds from now: 60 to 10800, 3600 by default.

Each repeat plays the Critical sound, a desk bell that climbs as it rings, whatever sound says. Anyone on the account can Acknowledge it from the notification itself, or from the app, and the repeats stop on every device.

An account can have 10 Critical notifications repeating at once. Past that, a new one is still delivered and still waits for acknowledgment until it expires, but doesn’t repeat, and the response says so with "repeats": false. Acknowledge, cancel or let one expire, and the next one repeats again. A replacement (replace) for one that’s repeating keeps its place.

Check on it

The response carries the notification’s id. Ask for it with the same key:

curl https://api.pocketbell.dev/v1/messages/msg_… \
  -H "Authorization: Bearer pb_live_…"

status is awaiting_acknowledgment, acknowledged, canceled or expired, with acknowledged_at and acknowledged_device once someone responds. deliveries counts the devices it’s queued for, sent to, delivered to (as each device reported it) and failed on.

Cancel it when the problem clears

curl -X POST https://api.pocketbell.dev/v1/messages/msg_…/cancel \
  -H "Authorization: Bearer pb_live_…"

Callbacks (Pro)

Add "callback": "https://…" and Pocketbell POSTs to it when the notification is acknowledged, or when it expires unacknowledged:

{
  "type": "message.acknowledged",
  "timestamp": "2026-09-28T02:21:07Z",
  "data": {
    "id": "msg_…",
    "source_id": "src_…",
    "created_at": "2026-09-28T02:14:00Z",
    "acknowledged_at": "2026-09-28T02:21:06Z"
  }
}

The type is message.acknowledged or message.expired. Callbacks are signed to the Standard Webhooks spec, with the webhook-id, webhook-timestamp and webhook-signature headers, so any Standard Webhooks library can verify them. The Source’s signing secret (whsec_…) is in the app, under the Source.

A callback that fails is retried. Addresses that resolve to a private, loopback or link-local network are refused.