--- layout: page title: "Push Notifications" description: "Instructions how to use the HTML5 push notifications platform from Home Assistant." date: 2016-08-17 21:58 sidebar: true comments: false sharing: true footer: true logo: html5.png ha_category: Notifications ha_release: 0.27 --- The `html5` notification platform enables you to receive push notifications to Chrome or Firefox, no matter where you are in the world. `html5` also supports Chrome and Firefox on Android, which enables native-app-like integrations without actually needing a native app. To enable this platform, add the following lines to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry notify: - name: NOTIFIER_NAME platform: html5 gcm_api_key: 'gcm-sender-key' gcm_sender_id: 'gcm-sender-id' ``` Configuration variables: - **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. - **gcm_api_key** (*Required if pushing to Chrome*): The API key provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome. - **gcm_sender_id** (*Required if pushing to Chrome*): The sender ID provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome. ### {% linkable_title Getting ready for Chrome %} - Create new project at [https://console.cloud.google.com/home/dashboard](https://console.cloud.google.com/home/dashboard). - Go to [https://console.cloud.google.com/apis/credentials/domainverification](https://console.cloud.google.com/apis/credentials/domainverification) and verify your domain. - After that, go to [https://console.firebase.google.com](https://console.firebase.google.com) and select import Google project, select the project you created. - Then, click the clogwheel on top left and select "Project settings". - Select Cloud messaging tab if under server key is button Regenerate key, click that. ### {% linkable_title Requirements %} The `html5` platform can only function if all of the following requirements are met: * You are using Chrome and/or Firefox on any desktop platform, ChromeOS, or Android. * Your Home Assistant instance is exposed to the world. * If using a proxy, HTTP basic authentication must be off for registering or unregistering for push notifications. It can be re-enabled afterwards. * `pywebpush` must be installed. `libffi-dev`, `libpython-dev`, and `libssl-dev` must be installed prior to `pywebpush` (i.e. `pywebpush` probably won't automatically install). * You have configured SSL for your Home Assistant. It doesn't need to be configured in Home Assistant though, i.e. you can be running [NGINX](/ecosystem/nginx/) in front of Home Assistant and this will still work. The certificate must be trustworthy (i.e. not self signed). * You are willing to accept the notification permission in your browser. ### {% linkable_title Setting up %} Assuming you have already added the platform to your configuration: 1. Open Home Assistant in Chrome or Firefox. 2. Assuming you have met all the [requirements](#requirements) above, you should see a new slider in the sidebar labeled Push Notifications. 3. Slide it to the on position. 4. Within a few seconds you should be prompted to allow notifications from Home Assistant. 5. Assuming you accept, that's all there is to it! 6. (Optional, but highly recommended!) Open the `html5_push_registrations.conf` file in your configuration directory. You will see a new entry for the browser you just added. Rename it from `unnamed device` to a name of your choice, which will make it easier to identify later. _Do not change anything else in this file!_ You need to restart Home Assistant after making any changes to the file. ### {% linkable_title Usage %} The `html5` platform accepts a standard notify payload. However, there are also some special features built in which you can control in the payload. Any JSON examples below can be [converted to YAML](https://www.json2yaml.com/) for automations. #### {% linkable_title Actions %} Chrome supports notification actions, which are configurable buttons that arrive with the notification and can cause actions on Home Assistant to happen when pressed. You can send [up to 2 actions](https://cs.chromium.org/chromium/src/third_party/WebKit/public/platform/modules/notifications/WebNotificationConstants.h?q=maxActions&sq=package:chromium&dr=CSs&l=14). ```json { "message": "Anne has arrived home", "data": { "actions": [ { "action": "open", "icon": "/static/icons/favicon-192x192.png", "title": "Open Home Assistant" }, { "action": "open_door", "title": "Open door" } ] } } ``` #### {% linkable_title Data %} Any parameters that you pass in the notify payload that aren't valid for use in the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`) will be sent back to you in the [callback events](#automating-notification-events). ```json { "title": "Front door", "message": "The front door is open", "data": { "my-custom-parameter": "front-door-open" } } ``` #### {% linkable_title Tag %} By default, every notification sent has a randomly generated UUID (v4) set as its _tag_ or unique identifier. The tag is unique to the notification, _not_ to a specific target. If you pass your own tag in the notify payload you can replace the notification by sending another notification with the same tag. You can provide a `tag` like so: ```json { "title": "Front door", "message": "The front door is open", "data": { "tag": "front-door-notification" } } ``` Example of adding a tag to your configuration. This won't create new notification if there already exists one with the same tag. ```yaml - alias: Push/update notification of sensor state with tag trigger: - platform: state entity_id: sensor.sensor action: service: notify.html5 data_template: message: "Last known sensor state is {% raw %}{{ states('sensor.sensor') }}{% endraw %}." data: data: tag: 'notification-about-sensor' ``` #### {% linkable_title Targets %} If you do not provide a `target` parameter in the notify payload a notification will be sent to all registered targets as listed in `html5_push_registrations.conf`. You can provide a `target` parameter like so: ```json { "title": "Front door", "message": "The front door is open", "target": "unnamed device" } ``` `target` can also be a string array of targets like so: ```json { "title": "Front door", "message": "The front door is open", "target": ["unnamed device", "unnamed device 2"] } ``` #### {% linkable_title Overrides %} You can pass any of the parameters listed [here](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/showNotification#Parameters) in the `data` dictionary. Please note, [Chrome specifies](https://cs.chromium.org/chromium/src/third_party/WebKit/public/platform/modules/notifications/WebNotificationConstants.h?q=maxActions&sq=package:chromium&dr=CSs&l=21) that the maximum size for an icon is 320px by 320px, the maximum `badge` size is 96px by 96px and the maximum icon size for an action button is 128px by 128px. #### {% linkable_title URL %} You can provide a URL to open when the notification is clicked by putting `url` in the data dictionary like so: ```json { "title": "Front door", "message": "The front door is open", "data": { "url": "https://google.com" } } ``` If no URL or actions are provided, interacting with a notification will open your Home Assistant in the browser. You can use relative URLs to refer to Home Assistant, i.e. `/map` would turn into `https://192.168.1.2:8123/map`. ### {% linkable_title Automating notification events %} During the lifespan of a single push notification, Home Assistant will emit a few different events to the event bus which you can use to write automations against. Common event payload parameters are: | Parameter | Description | |-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `action` | The `action` key that you set when sending the notification of the action clicked. Only appears in the `clicked` event. | | `data` | The data dictionary you originally passed in the notify payload, minus any parameters that were added to the HTML5 notification (`actions`, `badge`, `body`, `dir`, `icon`, `lang`, `renotify`, `requireInteraction`, `tag`, `timestamp`, `vibrate`). | | `tag` | The unique identifier of the notification. Can be overridden when sending a notification to allow for replacing existing notifications. | | `target` | The target that this notification callback describes. | | `type` | The type of event callback received. Can be `received`, `clicked` or `closed`. | You can use the `target` parameter to write automations against a single `target`. For more granularity, use `action` and `target` together to write automations which will do specific things based on what target clicked an action. #### {% linkable_title received event %} You will receive an event named `html5_notification.received` when the notification is received on the device. ```yaml - alias: HTML5 push notification received and displayed on device trigger: platform: event event_type: html5_notification.received ``` #### {% linkable_title clicked event %} You will receive an event named `html5_notification.clicked` when the notification or a notification action button is clicked. The action button clicked is available as `action` in the `event_data`. ```yaml - alias: HTML5 push notification clicked trigger: platform: event event_type: html5_notification.clicked ``` or ```yaml - alias: HTML5 push notification action button clicked trigger: platform: event event_type: html5_notification.clicked event_data: action: open_door ``` #### {% linkable_title closed event %} You will receive an event named `html5_notification.closed` when the notification is closed. ```yaml - alias: HTML5 push notification clicked trigger: platform: event event_type: html5_notification.closed ```