jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions
home-assistant.github.io/components/notify.html5/index.html
Travis CI 233bcdc1d8 Site updated at 2017-11-05 14:24:39 UTC
2017-11-05 14:24:39 +00:00

544 lines
36 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Push Notifications - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to use the HTML5 push notifications platform from Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/components/notify.html5/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Push Notifications">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/components/notify.html5/">
<meta property="og:type" content="article">
<meta property="og:description" content="Instructions how to use the HTML5 push notifications platform from Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Push Notifications">
<meta name="twitter:description" content="Instructions how to use the HTML5 push notifications platform from Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection, print" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header class='site-header'>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
<li><a href="/cookbook/">Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
<li><a href='#' class='show-search'><i class="icon-search"></i></a></li>
</ul>
</nav>
<div class='search-container' style='display: none'>
<div class='search'>
<i class="icon-search"></i>
<input id='search' placeholder='Search the docs…'>
<a href='#' class='close'><i class="icon-remove-sign"></i></a>
</div>
</div>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<header>
<h1 class="title indent">
Push Notifications
</h1>
</header>
<hr class="divider">
<p>The <code class="highlighter-rouge">html5</code> notification platform enables you to receive push notifications to Chrome or Firefox, no matter where you are in the world. <code class="highlighter-rouge">html5</code> also supports Chrome and Firefox on Android, which enables native-app-like integrations without actually needing a native app.</p>
<p>To enable this platform, add the following lines to your <code class="highlighter-rouge">configuration.yaml</code> file:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
<span class="s">notify</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">name</span><span class="pi">:</span> <span class="s">NOTIFIER_NAME</span>
<span class="s">platform</span><span class="pi">:</span> <span class="s">html5</span>
<span class="s">gcm_api_key</span><span class="pi">:</span> <span class="s1">'</span><span class="s">gcm-sender-key'</span>
<span class="s">gcm_sender_id</span><span class="pi">:</span> <span class="s1">'</span><span class="s">gcm-sender-id'</span>
</code></pre>
</div>
<p>Configuration variables:</p>
<ul>
<li><strong>name</strong> (<em>Optional</em>): Setting the optional parameter <code class="highlighter-rouge">name</code> allows multiple notifiers to be created. The default value is <code class="highlighter-rouge">notify</code>. The notifier will bind to the service <code class="highlighter-rouge">notify.NOTIFIER_NAME</code>.</li>
<li><strong>gcm_api_key</strong> (<em>Required if pushing to Chrome</em>): The API key provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome.</li>
<li><strong>gcm_sender_id</strong> (<em>Required if pushing to Chrome</em>): The sender ID provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome.</li>
</ul>
<h3><a class="title-link" name="getting-ready-for-chrome" href="#getting-ready-for-chrome"></a> Getting ready for Chrome</h3>
<ol>
<li>Create new project at <a href="https://console.cloud.google.com/home/dashboard">https://console.cloud.google.com/home/dashboard</a>.</li>
<li>Go to <a href="https://console.cloud.google.com/apis/credentials/domainverification">https://console.cloud.google.com/apis/credentials/domainverification</a> and verify your domain.</li>
<li>After that, go to <a href="https://console.firebase.google.com">https://console.firebase.google.com</a> and select import Google project, select the project you created.</li>
<li>Then, click the cogwheel on top left and select “Project settings”.</li>
<li>Select ‘Cloud Messaging’ tab, listed beneath Project Credentials will be your 152 character ‘Server Key’ and 12 digit ID ‘Sender ID’.</li>
</ol>
<h4><a class="title-link" name="verify-your-domain-with-hassio" href="#verify-your-domain-with-hassio"></a> Verify your domain with Hass.io</h4>
<ol>
<li>For verifying your domain you need to download a file in step 2.</li>
<li>Create a dictionary named “www” in you Hass.io configuration dictionary.</li>
<li>Place the file (something like this: google*.html) in the “www” directory.</li>
<li>You can open it by going to <strong>https://yourdomain/local/exact_file_name.html</strong></li>
<li>Proceed with step 3.</li>
</ol>
<h3><a class="title-link" name="requirements" href="#requirements"></a> Requirements</h3>
<p>The <code class="highlighter-rouge">html5</code> platform can only function if all of the following requirements are met:
(On Hass.io these requirements are already met.)</p>
<ul>
<li>You are using Chrome and/or Firefox on any desktop platform, ChromeOS or Android.</li>
<li>Your Home Assistant instance is exposed to the world.</li>
<li>If using a proxy, HTTP basic authentication must be off for registering or unregistering for push notifications. It can be re-enabled afterwards.</li>
<li><code class="highlighter-rouge">pywebpush</code> must be installed. <code class="highlighter-rouge">libffi-dev</code>, <code class="highlighter-rouge">libpython-dev</code>, and <code class="highlighter-rouge">libssl-dev</code> must be installed prior to <code class="highlighter-rouge">pywebpush</code> (i.e. <code class="highlighter-rouge">pywebpush</code> probably won’t automatically install).</li>
<li>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 <a href="/ecosystem/nginx/">NGINX</a> in front of Home Assistant and this will still work. The certificate must be trustworthy (i.e. not self signed).</li>
<li>You are willing to accept the notification permission in your browser.</li>
</ul>
<h3><a class="title-link" name="setting-up" href="#setting-up"></a> Setting up</h3>
<p>Assuming you have already added the platform to your configuration:</p>
<ol>
<li>Open Home Assistant in Chrome or Firefox.</li>
<li>Assuming you have met all the <a href="#requirements">requirements</a> above, you should see a new slider in the sidebar labeled Push Notifications.</li>
<li>Slide it to the on position.</li>
<li>Within a few seconds you should be prompted to allow notifications from Home Assistant.</li>
<li>Assuming you accept, that’s all there is to it!</li>
<li>(Optional, but highly recommended!) Open the <code class="highlighter-rouge">html5_push_registrations.conf</code> file in your configuration directory. You will see a new entry for the browser you just added. Rename it from <code class="highlighter-rouge">unnamed device</code> to a name of your choice, which will make it easier to identify later. <em>Do not change anything else in this file!</em> You need to restart Home Assistant after making any changes to the file.</li>
</ol>
<h3><a class="title-link" name="usage" href="#usage"></a> Usage</h3>
<p>The <code class="highlighter-rouge">html5</code> platform accepts a standard notify payload. However, there are also some special features built in which you can control in the payload.</p>
<p>Any JSON examples below can be <a href="https://www.json2yaml.com/">converted to YAML</a> for automations.</p>
<h4><a class="title-link" name="actions" href="#actions"></a> Actions</h4>
<p>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 <a href="https://cs.chromium.org/chromium/src/third_party/WebKit/public/platform/modules/notifications/WebNotificationConstants.h?q=maxActions&amp;sq=package:chromium&amp;dr=CSs&amp;l=14">up to 2 actions</a>.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Anne has arrived home"</span><span class="p">,</span><span class="w">
</span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"actions"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"action"</span><span class="p">:</span><span class="w"> </span><span class="s2">"open"</span><span class="p">,</span><span class="w">
</span><span class="nt">"icon"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/static/icons/favicon-192x192.png"</span><span class="p">,</span><span class="w">
</span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Open Home Assistant"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"action"</span><span class="p">:</span><span class="w"> </span><span class="s2">"open_door"</span><span class="p">,</span><span class="w">
</span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Open door"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h4><a class="title-link" name="data" href="#data"></a> Data</h4>
<p>Any parameters that you pass in the notify payload that aren’t valid for use in the HTML5 notification (<code class="highlighter-rouge">actions</code>, <code class="highlighter-rouge">badge</code>, <code class="highlighter-rouge">body</code>, <code class="highlighter-rouge">dir</code>, <code class="highlighter-rouge">icon</code>, <code class="highlighter-rouge">image</code>, <code class="highlighter-rouge">lang</code>, <code class="highlighter-rouge">renotify</code>, <code class="highlighter-rouge">requireInteraction</code>, <code class="highlighter-rouge">tag</code>, <code class="highlighter-rouge">timestamp</code>, <code class="highlighter-rouge">vibrate</code>) will be sent back to you in the <a href="#automating-notification-events">callback events</a>.</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Front door"</span><span class="p">,</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"The front door is open"</span><span class="p">,</span><span class="w">
</span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"my-custom-parameter"</span><span class="p">:</span><span class="w"> </span><span class="s2">"front-door-open"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h4><a class="title-link" name="tag" href="#tag"></a> Tag</h4>
<p>By default, every notification sent has a randomly generated UUID (v4) set as its <em>tag</em> or unique identifier. The tag is unique to the notification, <em>not</em> 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 <code class="highlighter-rouge">tag</code> like so:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Front door"</span><span class="p">,</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"The front door is open"</span><span class="p">,</span><span class="w">
</span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"tag"</span><span class="p">:</span><span class="w"> </span><span class="s2">"front-door-notification"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Example of adding a tag to your notification. This won’t create new notification if there already exists one with the same tag.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code> <span class="pi">-</span> <span class="s">alias</span><span class="pi">:</span> <span class="s">Push/update notification of sensor state with tag</span>
<span class="s">trigger</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">platform</span><span class="pi">:</span> <span class="s">state</span>
<span class="s">entity_id</span><span class="pi">:</span> <span class="s">sensor.sensor</span>
<span class="s">action</span><span class="pi">:</span>
<span class="s">service</span><span class="pi">:</span> <span class="s">notify.html5</span>
<span class="s">data_template</span><span class="pi">:</span>
<span class="s">message</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Last</span><span class="nv"> </span><span class="s">known</span><span class="nv"> </span><span class="s">sensor</span><span class="nv"> </span><span class="s">state</span><span class="nv"> </span><span class="s">is</span><span class="nv"> </span><span class="s">{{</span><span class="nv"> </span><span class="s">states('sensor.sensor')</span><span class="nv"> </span><span class="s">}}."</span>
<span class="s">data</span><span class="pi">:</span>
<span class="s">data</span><span class="pi">:</span>
<span class="s">tag</span><span class="pi">:</span> <span class="s1">'</span><span class="s">notification-about-sensor'</span>
</code></pre>
</div>
<h4><a class="title-link" name="targets" href="#targets"></a> Targets</h4>
<p>If you do not provide a <code class="highlighter-rouge">target</code> parameter in the notify payload a notification will be sent to all registered targets as listed in <code class="highlighter-rouge">html5_push_registrations.conf</code>. You can provide a <code class="highlighter-rouge">target</code> parameter like so:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Front door"</span><span class="p">,</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"The front door is open"</span><span class="p">,</span><span class="w">
</span><span class="nt">"target"</span><span class="p">:</span><span class="w"> </span><span class="s2">"unnamed device"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p><code class="highlighter-rouge">target</code> can also be a string array of targets like so:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Front door"</span><span class="p">,</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"The front door is open"</span><span class="p">,</span><span class="w">
</span><span class="nt">"target"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"unnamed device"</span><span class="p">,</span><span class="w"> </span><span class="s2">"unnamed device 2"</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h4><a class="title-link" name="overrides" href="#overrides"></a> Overrides</h4>
<p>You can pass any of the parameters listed <a href="https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/showNotification#Parameters">here</a> in the <code class="highlighter-rouge">data</code> dictionary. Please note, <a href="https://cs.chromium.org/chromium/src/third_party/WebKit/public/platform/modules/notifications/WebNotificationConstants.h?q=maxActions&amp;sq=package:chromium&amp;dr=CSs&amp;l=21">Chrome specifies</a> that the maximum size for an icon is 320px by 320px, the maximum <code class="highlighter-rouge">badge</code> size is 96px by 96px and the maximum icon size for an action button is 128px by 128px.</p>
<h4><a class="title-link" name="url" href="#url"></a> URL</h4>
<p>You can provide a URL to open when the notification is clicked by putting <code class="highlighter-rouge">url</code> in the data dictionary like so:</p>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Front door"</span><span class="p">,</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"The front door is open"</span><span class="p">,</span><span class="w">
</span><span class="nt">"data"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://google.com"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>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. <code class="highlighter-rouge">/map</code> would turn into <code class="highlighter-rouge">https://192.168.1.2:8123/map</code>.</p>
<h3><a class="title-link" name="automating-notification-events" href="#automating-notification-events"></a> Automating notification events</h3>
<p>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.</p>
<p>Common event payload parameters are:</p>
<table>
<thead>
<tr>
<th>Parameter</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="highlighter-rouge">action</code></td>
<td>The <code class="highlighter-rouge">action</code> key that you set when sending the notification of the action clicked. Only appears in the <code class="highlighter-rouge">clicked</code> event.</td>
</tr>
<tr>
<td><code class="highlighter-rouge">data</code></td>
<td>The data dictionary you originally passed in the notify payload, minus any parameters that were added to the HTML5 notification (<code class="highlighter-rouge">actions</code>, <code class="highlighter-rouge">badge</code>, <code class="highlighter-rouge">body</code>, <code class="highlighter-rouge">dir</code>, <code class="highlighter-rouge">icon</code>, <code class="highlighter-rouge">image</code>, <code class="highlighter-rouge">lang</code>, <code class="highlighter-rouge">renotify</code>, <code class="highlighter-rouge">requireInteraction</code>, <code class="highlighter-rouge">tag</code>, <code class="highlighter-rouge">timestamp</code>, <code class="highlighter-rouge">vibrate</code>).</td>
</tr>
<tr>
<td><code class="highlighter-rouge">tag</code></td>
<td>The unique identifier of the notification. Can be overridden when sending a notification to allow for replacing existing notifications.</td>
</tr>
<tr>
<td><code class="highlighter-rouge">target</code></td>
<td>The target that this notification callback describes.</td>
</tr>
<tr>
<td><code class="highlighter-rouge">type</code></td>
<td>The type of event callback received. Can be <code class="highlighter-rouge">received</code>, <code class="highlighter-rouge">clicked</code> or <code class="highlighter-rouge">closed</code>.</td>
</tr>
</tbody>
</table>
<p>You can use the <code class="highlighter-rouge">target</code> parameter to write automations against a single <code class="highlighter-rouge">target</code>. For more granularity, use <code class="highlighter-rouge">action</code> and <code class="highlighter-rouge">target</code> together to write automations which will do specific things based on what target clicked an action.</p>
<h4><a class="title-link" name="received-event" href="#received-event"></a> received event</h4>
<p>You will receive an event named <code class="highlighter-rouge">html5_notification.received</code> when the notification is received on the device.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="pi">-</span> <span class="s">alias</span><span class="pi">:</span> <span class="s">HTML5 push notification received and displayed on device</span>
<span class="s">trigger</span><span class="pi">:</span>
<span class="s">platform</span><span class="pi">:</span> <span class="s">event</span>
<span class="s">event_type</span><span class="pi">:</span> <span class="s">html5_notification.received</span>
</code></pre>
</div>
<h4><a class="title-link" name="clicked-event" href="#clicked-event"></a> clicked event</h4>
<p>You will receive an event named <code class="highlighter-rouge">html5_notification.clicked</code> when the notification or a notification action button is clicked. The action button clicked is available as <code class="highlighter-rouge">action</code> in the <code class="highlighter-rouge">event_data</code>.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="pi">-</span> <span class="s">alias</span><span class="pi">:</span> <span class="s">HTML5 push notification clicked</span>
<span class="s">trigger</span><span class="pi">:</span>
<span class="s">platform</span><span class="pi">:</span> <span class="s">event</span>
<span class="s">event_type</span><span class="pi">:</span> <span class="s">html5_notification.clicked</span>
</code></pre>
</div>
<p>or</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="pi">-</span> <span class="s">alias</span><span class="pi">:</span> <span class="s">HTML5 push notification action button clicked</span>
<span class="s">trigger</span><span class="pi">:</span>
<span class="s">platform</span><span class="pi">:</span> <span class="s">event</span>
<span class="s">event_type</span><span class="pi">:</span> <span class="s">html5_notification.clicked</span>
<span class="s">event_data</span><span class="pi">:</span>
<span class="s">action</span><span class="pi">:</span> <span class="s">open_door</span>
</code></pre>
</div>
<h4><a class="title-link" name="closed-event" href="#closed-event"></a> closed event</h4>
<p>You will receive an event named <code class="highlighter-rouge">html5_notification.closed</code> when the notification is closed.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="pi">-</span> <span class="s">alias</span><span class="pi">:</span> <span class="s">HTML5 push notification clicked</span>
<span class="s">trigger</span><span class="pi">:</span>
<span class="s">platform</span><span class="pi">:</span> <span class="s">event</span>
<span class="s">event_type</span><span class="pi">:</span> <span class="s">html5_notification.closed</span>
</code></pre>
</div>
<h3><a class="title-link" name="making-notifications-work-with-nginx-proxy" href="#making-notifications-work-with-nginx-proxy"></a> Making notifications work with NGINX proxy</h3>
<p>If you use <a href="/ecosystem/nginx/">NGINX</a> as an proxy with authentication in front of your Home Assistant instance, you may have trouble with receiving events back to Home Assistant. It’s because of authentication token that cannot be passed through the proxy.</p>
<p>To solve the issue put additional location into your nginx site’s configuration:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>location /api/notify.html5/callback <span class="o">{</span>
<span class="k">if</span> <span class="o">(</span><span class="nv">$http_authorization</span> <span class="o">=</span> <span class="s2">""</span><span class="o">)</span> <span class="o">{</span> <span class="k">return </span>403; <span class="o">}</span>
allow all;
proxy_pass http://localhost:8123;
proxy_set_header Host <span class="nv">$host</span>;
proxy_redirect http:// https://;
<span class="o">}</span>
</code></pre>
</div>
<p>This rule check if request have <code class="highlighter-rouge">Authorization</code> HTTP header and bypass the htpasswd (if you use one).</p>
<p>If you still have the problem, even with mentioned rule, try to add this code:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code> proxy_set_header Authorization <span class="nv">$http_authorization</span>;
proxy_pass_header Authorization;
</code></pre>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/notify.html5.markdown'>Edit this page on GitHub</a></div>
<div class='brand-logo-container section'>
<img src='/images/supported_brands/html5.png' />
</div>
<div class='section'>
Introduced in release: 0.27
</div>
<div class='section'>
Source:
<a href='https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/notify/html5.py'>notify/html5.py</a>
</div>
<div class='section'>
This is a platform for
<a href='/components/notify/'>the Notifications component</a>.
</div>
<div class='section'>
<h1 class="title delta">Category Notifications</h1>
<ul class='divided'>
<li>
<a href='/components/notify.apns/'>APNS</a>
</li>
<li>
<a href='/components/notify.aws_lambda/'>AWS Lambda</a>
</li>
<li>
<a href='/components/notify.aws_sns/'>AWS SNS</a>
</li>
<li>
<a href='/components/notify.aws_sqs/'>AWS SQS</a>
</li>
<li>
<a href='/components/notify.ciscospark/'>Cisco Spark</a>
</li>
<li>
<a href='/components/notify.clicksend/'>ClickSend SMS</a>
</li>
<li>
<a href='/components/notify.clicksend_tts/'>ClickSend text-to-speech</a>
</li>
<li>
<a href='/components/notify.clickatell/'>Clickatell SMS</a>
</li>
<li>
<a href='/components/notify.command_line/'>Command line Notify</a>
</li>
<li>
<a href='/components/notify.discord/'>Discord</a>
</li>
<li>
<a href='/components/notify.ecobee/'>Ecobee Notify</a>
</li>
<li>
<a href='/components/notify.facebook/'>Facebook Messenger</a>
</li>
<li>
<a href='/components/notify.file/'>File</a>
</li>
<li>
<a href='/components/notify.free_mobile/'>Free Mobile</a>
</li>
<li>
<a href='/components/notify.gntp/'>GNTP (Growl)</a>
</li>
<li>
<a href='/components/notify.hipchat/'>HipChat</a>
</li>
<li>
<a href='/components/notify.instapush/'>Instapush</a>
</li>
<li>
<a href='/components/notify.xmpp/'>Jabber (XMPP)</a>
</li>
<li>
<a href='/components/notify.joaoapps_join/'>Join Notify</a>
</li>
<li>
<a href='/components/notify.knx/'>KNX Notify</a>
</li>
<li>
<a href='/components/notify.kodi/'>Kodi</a>
</li>
<li>
<a href='/components/notify.webostv/'>LG WebOS TV notifications</a>
</li>
<li>
<a href='/components/notify.lametric/'>LaMetric Notify</a>
</li>
<li>
<a href='/components/notify.lannouncer/'>Lannouncer</a>
</li>
<li>
<a href='/components/notify.llamalab_automate/'>LlamaLab Automate</a>
</li>
<li>
<a href='/components/notify.mqtt/'>MQTT Notifications</a>
</li>
<li>
<a href='/components/mailgun/'>Mailgun</a>
</li>
<li>
<a href='/components/notify.mailgun/'>Mailgun Notify</a>
</li>
<li>
<a href='/components/notify.matrix/'>Matrix</a>
</li>
<li>
<a href='/components/notify.message_bird/'>MessageBird</a>
</li>
<li>
<a href='/components/notify.mysensors/'>MySensors Notify</a>
</li>
<li>
<a href='/components/notify.mycroft/'>Mycroft AI</a>
</li>
<li>
<a href='/components/notify.nfandroidtv/'>Notifications for Android TV / FireTV</a>
</li>
<li>
<a href='/components/notify.group/'>Notify Group</a>
</li>
<li>
<a href='/components/notify.nma/'>Notify My Android</a>
</li>
<li>
<a href='/components/notify.prowl/'>Prowl</a>
</li>
<li>
Push Notifications
</li>
<li>
<a href='/components/notify.pushbullet/'>Pushbullet</a>
</li>
<li>
<a href='/components/notify.pushetta/'>Pushetta</a>
</li>
<li>
<a href='/components/notify.pushover/'>Pushover</a>
</li>
<li>
<a href='/components/notify.pushsafer/'>Pushsafer</a>
</li>
<li>
<a href='/components/notify.rest/'>REST</a>
</li>
<li>
<a href='/components/notify.rocketchat/'>Rocket.Chat</a>
</li>
<li>
<a href='/components/notify.smtp/'>SMTP</a>
</li>
<li>
<a href='/components/notify.sendgrid/'>SendGrid</a>
</li>
<li>
<a href='/components/notify.simplepush/'>Simplepush</a>
</li>
<li>
<a href='/components/notify.slack/'>Slack</a>
</li>
<li>
<a href='/components/notify.syslog/'>Syslog</a>
</li>
<li>
<a href='/components/notify.telegram/'>Telegram</a>
</li>
<li>
<a href='/components/notify.telstra/'>Telstra</a>
</li>
<li>
<a href='/components/notify.twilio_call/'>Twilio Call</a>
</li>
<li>
<a href='/components/notify.twilio_sms/'>Twilio SMS</a>
</li>
<li>
<a href='/components/notify.twitter/'>Twitter</a>
</li>
<li>
<a href='/components/notify.yessssms/'>Yesss SMS</a>
</li>
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a> (no support!).<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">home-assistant.io</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
</div>
</div>
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css" />
<script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js"></script>
<script type="text/javascript">
docsearch({
apiKey: 'ae96d94b201c5444c8a443093edf3efb',
indexName: 'home-assistant',
inputSelector: '#search',
debug: false // Set debug to true if you want to inspect the dropdown
});
document.querySelector('.search .close').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'none';
});
document.querySelector('.show-search').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'block';
document.getElementById('toggle').checked = false;
document.querySelector('.search-container input').focus();
});
</script>
</body>
</html>
Reference in a new issue View git blame Copy permalink