Acknowledgement and receipts

Acknowledging an alert tells the sender, and everyone else who received it, that a person has taken it. Use it when an alert needs an owner: an outage, a failed payment run, a door left open.

Ask for acknowledgement

An alert requires acknowledgement when any of these is true:

• The request sets "require_ack": true.
• The level is urgent.
• The channel owner turned on Require acknowledgement for the alert’s level in Alert levels.

curl -X POST "$SEND_URL" \
  -H 'Content-Type: application/json' \
  -d '{"alert": {"title": "Payment run failed"}, "level": "high", "require_ack": true}'

Until it is acknowledged, the alert counts as Needs ack in the inbox, and urgent alerts keep reminding the recipients.

Acknowledge in the app

Open the alert and choose Acknowledge. One acknowledgement is enough: the alert becomes Acked on every device that received it, and reminders stop.

If the device is offline, the app saves the acknowledgement and shows Ack queued. It sends it as soon as the device is back online.

If the alert asks for a callback, the app asks first whether the server should send it: Acknowledge only or Acknowledge and send Callback.

Check a receipt

When an alert requires acknowledgement, or the request sets "receipt": true, the response includes message.receipt_id. Look up its state with the token from the same send URL — the part after /v1/send/:

curl -H "Authorization: Bearer $SEND_TOKEN" "https://<api-host>/v1/receipts/$RECEIPT_ID"

{
  "receipt": {
    "id": "rcp_9a02…",
    "message_id": "msg_4f1c…",
    "status": "acked",
    "acknowledged": true,
    "acknowledged_at": "2026-10-27T08:15:30Z",
    "emergency": true,
    "retry_seconds": 60,
    "emergency_expires_at": "2026-10-27T09:14:02Z",
    "expired": false
  }
}

Field	Description
status	open, read, acked, or resolved.
acknowledged, acknowledged_at	Whether and when someone acknowledged the alert.
emergency, retry_seconds, emergency_expires_at	Reminder settings for urgent alerts.
expired	true when urgent reminders ran out without an acknowledgement. Use it to escalate another way.
callback	Present when a callback was requested: its status, attempt_count, and delivered_at.

Only the send URL that sent the alert can read its receipt; any other send URL’s token gets 404 not_found, and a token that is not a send URL gets 401 unauthorized.

Polling is fine for scripts that wait a short time. To be told instead, use an acknowledgement callback.