Questions and receipts

Ask a question with one-tap answers, see who read a notification, and get the answer back at your server as a signed callback.

A notification can ask a question you answer with one tap, and your script hears the answer. It can also tell you when it was opened.

Ask a question#

Add replies to a send. The buttons appear on the notification itself, so the answer is one tap on the Lock Screen.

curl https://nowlark.com/v1/notify \
  -H "X-Nowlark-Key: nlk_…" -H "Content-Type: application/json" \
  -d '{"source":"Deploy","title":"Deploy v2.4 to production?","body":"All checks passed",
       "replies":"approve_deny","callback_url":"https://yourcompany.com/nowlark",
       "callback_secret":"a-long-private-string","reply_within":3600}'

DEPLOY · nowDeploy v2.4 to production?All checks passed

ApproveDeny

Approve needs the phone unlocked. Deny does not.

`replies`	Buttons
`approve_deny`	Approve, Deny
`yes_no`	Yes, No
`approve_deny_later`	Approve, Deny, Later
`yes_no_later`	Yes, No, Later

The first answer is the answer. Two devices tapping at once cannot both win; the other is told what stands.
Later is an answer, not a snooze. It closes the question.
reply_within keeps the question open from 10 seconds up to 7 days. After that a reply is refused and the receipt says expired.
Answering counts as reading: the notification stops repeating.
Questions are answered on the iPhone.

How your script hears back#

Your scriptasks the question

You tap Approveon any device

Signed callbackand a receipt to read

Two ways back: Nowlark calls you, or you ask it.

Ask it. GET /v1/receipts/{id} with your key returns the state:

{"id":"ntf_…","state":"sent","acknowledged":true,"read":true,"delivered":2,
 "repeating":false,"expired":false,"reply_state":"answered","reply":"approve","callback":"delivered"}

Field	Means
`state`	`scheduled` (waiting), `sent`, or `failed` (refused when it fired, with the reason)
`acknowledged`	Opened or read on any device
`repeating`	Still alerting because nobody has opened it
`expired`	An urgent alert that ran out of repeats unopened
`reply_state`	`waiting`, `answered` or `expired` (empty when no question was asked)
`callback`	`pending`, `delivered` or `failed` (empty when none was asked for)

Be called. With callback_url, Nowlark posts once when the notification is first opened, and again with the answer if you asked a question. If you gave a callback_secret, every post is signed with X-Nowlark-Signature, so your server can reject anything that did not come from Nowlark. Act only on the replied event, not on acknowledged, which only means it was opened.

A failed callback is tried again after 30 seconds, 5 minutes, 30 minutes and 2 hours.
The address must be https and public. Nowlark does not follow redirects, and gives your server 5 seconds.
Treat a callback as a hint and confirm with the receipt, which needs your key.

Questions to a team#

On a team channel every member gets the question, and the first to answer settles it for everyone. The others see the answer that stands in their history and stop being alerted. The receipt names who answered, by the name they chose for the team.

Next: teams and channels.

PreviousSchedule, repeat and escalate NextSources, tones and your feed