Push notifications

Push notifications tell you when an agent needs you or is done, while OAR is not open in front of you: a question is waiting, a turn finished, a plan is ready. They are off by default and you switch them on separately on each device.

Your own relay sends them to your devices through the push service of your browser's vendor, using the standard web push library and its own VAPID keys. No OAR server is involved. The relay creates the keys the first time it starts and keeps them in its database, so they survive restarts. The text of a notification is only what you allow under What a notification shows: by default, a generic line without any conversation text.

What you need #

• A secure page. Open OAR over HTTPS, or on localhost. On any other address the browser does not offer push, and the Notifications settings say "Push requires a secure context. Open the app over HTTPS (or localhost) to enable notifications on this device." See Install as an app for the same rule.
• A browser with web push. It needs service workers, the Push API and the Notification API. Otherwise the settings say "This browser does not support Web Push notifications." (or "...service workers, which push notifications require.").
• The same on every system. OAR checks for these browser features and nothing else; it has no separate iOS rule. If your iPhone or iPad browser does not offer them, the Notifications settings say so.

Switching it on #

Do this on every device that should get notifications. The setting is saved per device, so switching it on in your laptop's browser does nothing for your phone.

1. Open Settings → Notifications.
2. Turn on Enable push notifications on this device.
3. Allow notifications when the browser asks. The prompt only ever appears after you click the switch, never when the page loads.
4. The status line reads "Push notifications are enabled on this device. They are only sent while no device has the app open." and the other controls unlock. (The exact rule is that no device has OAR visible in the foreground; see When no notification is sent.)
5. Choose the events and what the notifications show (below).

There is no test-notification button. To check that it works, leave OAR in the background (or close its tab) and let a short turn finish.

Turning the switch off again keeps the device in the list, marked disabled, and stops sending to it. Turning it on again is instant.

The device list #

At the bottom of the tab, Devices lists every device subscribed on this relay, newest change first. A row shows:

• the device name (for example Android Chrome; it is chosen from the browser and system, or Unnamed device), with (this device) on your own and disabled where it is switched off;
• Last delivery: when a notification last reached it, or never, plus the last error if the last attempt failed.

Rename asks for a new name (up to 80 characters). Revoke asks for confirmation, removes the device from the relay and, on the device you are using, also removes its subscription from the browser. Another device that you revoke from here stops receiving at once, but its browser cannot be told from here: the browser keeps its own subscription until you remove it there. On that device, open Settings → Notifications; the switch shows off. Turn it on again to receive notifications, or remove the site's notification permission in that browser's site settings to drop the subscription for good.

The events #

Each event has its own switch under Notify about. The switches belong to the device, so your phone and your laptop can differ.

When no notification is sent #

• While a device has OAR in the foreground. If any of your devices shows OAR on screen, nothing is sent to any device. A visible page tells the relay so every 30 seconds, and the relay counts a device as active for 90 seconds after its last report. A page that is hidden reports it at once. If the relay cannot tell, it does not send.
• For a turn another agent started. When an agent on another relay (or a session started by an agent) prompts a session, that turn sends no Turn completed and no Turn failed: the agent is the one waiting and reports to you itself. See agent notes. Questions still reach you.
• For a turn that answers relay events. A turn started by a relay event sends neither, for the same reason; a watcher that answers events pushes on its own when something matters. Questions are unchanged.
• Events you switched off on that device, or a device that is switched off.

A notification that cannot be delivered right away is kept by the push service for up to 12 hours.

What a notification shows #

Three settings, also per device, decide how much of the conversation leaves the relay.

With Message preview on None (generic text), the body is a fixed line:

With a preview, the body is the question's text, the reply (or the error text of a failed turn), or the plan board's title. Full text is cut at 2000 characters.

The notification also carries a few identifiers the app needs to open the right conversation (the conversation, question, board or message). A question's short choices travel with it as well, whatever the preview setting, because they become the buttons (see Answering from the notification).

Three events ignore the preview setting. CLI went offline always shows its fixed line. Host suspend fired or was dropped always shows its own message ("All agents finished; the host is suspending now." or "Queued host suspend dropped: relay ..."). Queued relay restart waited its maximum time always shows its own message too, such as "The queued relay restart has waited 30 min for 2 sessions. Restart now, keep waiting or cancel it.".

For more privacy, leave the title and preview off: then nothing from your conversations is in the notification.

Tapping a notification #

Tapping a notification opens OAR on that conversation (a notification without a conversation, such as CLI offline, opens OAR itself). If OAR is already open in a window, that window comes forward and shows the conversation; otherwise a new window opens. Each event gets its own notification: they stack and do not replace one another.

Answering from the notification #

A question notification can carry buttons for the question's choices:

• up to three choices, and no more buttons than your device shows;
• a choice longer than 120 characters gets no button, and a button's label is shortened to 40 characters (the answer sent is the full choice);
• tapping a button sends that answer to the relay without opening OAR, as long as the question is still waiting and the browser is signed in to the relay.

If the answer does not land (the question was answered elsewhere, has expired, or you are offline), the tap opens the conversation instead, so you can see why. See question cards.

Several devices, expired subscriptions, a new address #

• Several devices. Every device you switched on gets each notification whose event it has switched on. The foreground rule applies to all of them together.
• A subscription that expired. When the push service reports that a subscription no longer exists, the relay removes the device from the list by itself. A device that keeps failing for another reason is removed after 8 failed sends in a row. Switch the setting on again on that device to subscribe it afresh.
• After the relay's address changes. A subscription belongs to the page you switched it on from. Open OAR at the new address on each device and look at Settings → Notifications: a device that is not subscribed there shows the switch off. The old entry stays in the list until you Revoke it or the push service reports it gone. The relay keeps its push keys across restarts, so a restart on the same address does not need a new setup.

Troubleshooting #

See also Settings for the list of controls, and usage limit pause for how a paused turn notifies.