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; its buttons are its 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.

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 answered questions a month and Pro has no limit; only questions that reached a device count. When the month’s answers run out, you get one notification saying so, and new questions are refused with the error question_limit until the month resets, so your script always knows.