Questions

A notification can ask. Give it up to three options and they appear as buttons on it. Tap one on any of your devices, right from the Lock Screen, and the answer goes back to whatever asked.

Ask a question

curl https://api.pocketbell.dev/v1/messages \
  -H "Authorization: Bearer pb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy to production?", "message": "jobkore-api 4f2a91c",
       "priority": "important", "options": ["Approve", "Deny"], "expire": 1800}'

• options is one to three labels, up to 40 characters each. Put the likely answer first: a banner may show only the first two.
• expire is how long the question waits, in seconds from now: 60 to 10800, 3600 by default.
• A question can’t also have link actions, progress, deliver_at or replace: its buttons are its answers, it’s asked when it’s sent, and it stays until it’s answered.
• With "priority": "critical", it repeats until someone answers.

Answering needs the device unlocked, so a locked phone can’t answer for you. The first answer counts, on whichever device it’s given. The question clears from your other devices, and the message shows the answer and where it came from.

Priority works as usual. A critical question repeats until it’s answered, canceled or expires. Acknowledging doesn’t close a question: only an answer does.

Get the answer

Ask for the message with the same key:

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

status is awaiting_answer until someone answers, then answered, with answer (the label that was tapped), answered_device and answered_at. If nobody answers in time it becomes expired, and nothing is ever chosen for you: what an unanswered question means is up to your script.

A script can simply wait for it:

id=msg_…
while :; do
  status=$(curl -s https://api.pocketbell.dev/v1/messages/$id \
    -H "Authorization: Bearer pb_live_…" | jq -r .status)
  [ "$status" != awaiting_answer ] && break
  sleep 5
done

Cancel a question you no longer need, as with a Critical notification: POST /v1/messages/{id}/cancel.

Callbacks (Pro)

Add "callback": "https://…" and Pocketbell POSTs to it the moment the question is answered, or when it expires:

{
  "type": "message.answered",
  "timestamp": "2026-09-28T14:02:12Z",
  "data": {
    "id": "msg_…",
    "source_id": "src_…",
    "created_at": "2026-09-28T14:01:40Z",
    "answer": "Approve",
    "answered_device": "iPhone",
    "answered_at": "2026-09-28T14:02:11Z"
  }
}

The type is message.answered or message.expired. Callbacks are signed to the Standard Webhooks spec, the same way as Critical callbacks.

Limits

A question counts as one notification. Free includes 30 questions a month, and Pro has no limit. Past the 30, a new question is refused with 429 and the code question_limit until the month turns (UTC), so your script always knows; notifications without options still go. An answer is never refused because of the limit.