This is a wiki topic, regular members as well as staff may edit it freely and are encouraged to do so! The content will eventually be migrated somewhere in the main documentation when it’s stabilized and enough feedback has been received. When replying to posts on this series, please try to stay on-topic - there will be several of them, each covering a particular feature or area, so please look for the appropriate topic and reply there, or create a new topic. Thanks! 
This article will introduce one of the advanced web technologies used by the HABot UI: web push notifications, allowing you to receive rich notifications to your desktop computer or (Android) phone with the Web Push API standard. This feature requires a “secure origin”: it will only be available over valid HTTPS with a trusted certificate, and will be disabled over unsecure HTTP (except on localhost). Follow HABot Walkthrough (3/n): Add to Home Screen (or Desktop) for more details, since the requirements are basically the same as the Add to Home Screen feature - use the myopenhab.org service if in doubt.
The Web Push API allow applications to send push notifications to subscribed browsers, it has evolved from a specific implementation for Chrome to a vendor-agnostic standard.
Indeed, Web Push used to require a cloud service account and an API key from the browser vendor (i.e. Google at the time) but it’s not the case anymore: the HABot backend contains an implementation of the Voluntary Application Server Identification (VAPID) scheme described in RFC 8292 to identify itself directly to web push servers from browser vendors which support it: Google (Chrome), Mozilla (Firefox) and Microsoft (Edge). See caniuse.com for complete browser support. Note: Safari currently doesn’t support the Push API, therefore notifications cannot be sent to iOS devices with this scheme.
Again, this doesn’t require you to personally subscribe to any cloud service, not even openHAB Cloud or myopenhab.org (if you deploy HTTPS yourself or with a locally trusted certificate); your openHAB server will talk directly to the push server set up during the subscription. Of course, you still need Internet access both on the openHAB server and your desktop or phone since the notification payloads will transit (in encrypted form) through the push servers.
HABot can not only receive textual notifications, but can also reference a saved card in your Card deck via tags to present along with the message when the notification is clicked.
Subscribing to Notifications
First, you need to subscribe to the notifications on each device you wish them to be sent to.
Go to HABot’s settings screen and click the “Enable/test push notifications” option.
You might see some popup (different for each browser/device) requesting you to grant notifications for HABot’s site. Click the “Allow” button or similar:
Please be patient during this step, it can take up to 30 seconds, especially the first time or if you’re using a Raspberry Pi or other for openHAB - cryptographic keys have to be generated to identify (“voluntary identify”) your openHAB instance to push servers. If you ever need to access them or delete them (they will be recreated if necessary), they are stored in the userdata/habot/vapid_keys file. Subscriptions for your devices are stored in a JSONDB database stored in userdata/jsondb/habot_webpush_subscriptions.json. Currently there is no method to unsubscribe a device other than removing entries manually from the database.
If everything goes well, you will receive a test notification - how they are presented depend on your browser and device, the following screenshots show how they may appear:
Pushing Notifications
You can push notifications to all subscribed HABot clients from your openHAB rules (textual or with the experimental engine):
With Textual Rules
You can send web push notifications from your rules with the sendHABotNotification action:
The simplest variant of this action requires only a message. See below for advanced scenarios.
If HABot is not opened and focused, the notification will be displayed with your OS’ native UI (like the test notification screenshots above). Clicking on the notification will open the chat screen if necessary (or focus to one already in the background), and make HABot “say” the message. If a chat session is already in the foreground, the message will simply be added to it.
Pushed notification messages are marked with a “Notification” label above the chat bubble.
With the Experimental “Next-Gen” Rule Engine
If the next-gen rule engine is installed, a new action module will be added to the “Then” section of rules in Paper UI;
Alternatively, by using the create-rule intent/skill from HABot, you can create quick or throwaway rules using a simplified interface, and they may include a notification:
Displaying Cards along with Notifications
You can make HABot display one of the saved cards in your Card deck with the notification message. This is useful for instance to display webcams when an intrusion alarm was detected, thermostat controls when the temperature falls outside a predefined range, and so on.
There are two ways to identify a card to show: explicitely with its UID, or by matching tags applied to the card.
-
The card UID is an identifier randomly set for the card when it’s created, you can view in the browser’s address bar when working on the card in the Card designer: it’s the last part of the URL after
/designer/(in the below example it’sfaf00b48-2195-b7b4-afa6-1e32399adab5):
-
Tags on cards are a separate concept than attributes or tags on items; you can choose them any way you like, in the Card designer, when selecting the root HbCard component.
If multiple tags are provided, all have to match on the target card.
Then, in your textual rules, you may use one of those actions:
sendHABotNotificationWithCard(String message, String cardUID)
or
sendHABotNotificationWithTags(String message, List<Object> tags)
For example:
sendHABotNotificationWithCard("Notification message with an explicit card",
"9d84b626-0a34-a85f-c984-6fd5ec9ec233")
sendHABotNotificationWithTags("Notification message with a card matching tags",
newArrayList("notification", "heating", "alarm"))
In the next-gen rule engine action, you can configure the cardUID or tags similarly. The cardUID has priority over the tags.
In the create-rule skill, specifying the cardUID is not supported - you can only select existing tags from your cards.
This makes it really easy for the cases when you want openHAB do perform a simple task by itself later (at a specified time, or when something happens), then notify you when it’s been done, and present you the information so you assess it and continue the interaction if necessary:
Known Issues
Those issues around push notifications are known:
- On desktop Chrome or Firefox, the notification will not be displayed unless the browser is already running - this does not apply to Edge or Android Chrome
- Microsoft Edge cannot register the service worker necessary for notifications in an authenticated scenario, due to this bug.
- Sometimes (mostly on desktops, not Android) clicking a notification will not open the chat session, or will open another window although one is already open in a tab
- When HABot has been installed as a app with desktop Chrome, clicking a notification will not open the app if it’s not already open
- The openHAB icon will not appear on notifications if the credentials have to be supplied again (even if the “Save openHAB Cloud Credentials” feature in settings is used), the standard icon will be displayed instead
- In an authenticated scenario, login may be required even if the “Save openHAB Cloud Credentials” feature in settings is used
