jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-28 11:47:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

clarify notifications building block page (#31803)

Browse Source 
* update notifications general page

* fix styling, add notify groups

* add a few glossary links

* fix style for lint

* add a MY link for developer tools

* fix the long name of the example actions

* Tiny style tweaks

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
John Taseff 2024-03-15 08:27:12 +01:00 committed by GitHub
parent 74549d919e
commit 495b069f20
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 40 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
source/_integrations/notify.markdown
View File

@ -11,9 +11,9 @@ ha_domain: notify
ha_integration_type: entity
---
The `notify` integration makes it possible to send notifications to a wide variety of platforms. To use it you have to setup at least one notification target (notifier), check the [integrations list](/integrations/#notifications) for one that fits your use case.
The **Notify** {% term integration %} makes it possible to send notifications to a wide variety of platforms. To use it, you have to set up at least one notification target (notifier). Check the [integrations list](/integrations/#notifications) for one that fits your use case.
If you want to send notifications to the Home Assistant web interface, you may use the [Persistent Notification integration](/integrations/persistent_notification/). The Persistent Notification integration is also available as an automatically configured notifier. See [its documentation](/integrations/persistent_notification/) for more details.
If you want to send notifications to the Home Assistant web interface, you may use the [Persistent Notification integration](/integrations/persistent_notification/). It is available as an automatically configured notifier. See [its documentation](/integrations/persistent_notification/) for more details.
{% include integrations/building_block_integration.md %}
@ -28,43 +28,64 @@ Once loaded, the `notify` platform will expose a service that can be called to s
| `target` | yes | Some platforms allow specifying a recipient that will receive the notification. See your platform page if it is supported.
| `data` | yes | On platforms who have extended functionality. See your platform page if it is supported.
The notify integration supports specifying [templates](/docs/configuration/templating/). This will allow you to use the current state of Home Assistant in your notifications.
## Usage
In an [action](/getting-started/automation-action/) of your [automation setup](/getting-started/automation/) it could look like this with a customized subject.
The different **Notify** integrations you have set up will each show up as a different automation {% term action %} or {% term service %} call that you can use.
Be aware that you might want to change the actual service to whatever service you are actually using since `notify.notify` is shorthand for the first notify service the system can find and might therefore not be working as intended.
One notification integration is automatically included, the Persistent Notifications which creates a notification in the sidebar of the web interface of Home Assistant. This can be chosen with the action named "Notifications: Send a persistent notification" which uses the service `notify.persistent_notification`.
```yaml
action:
service: notify.notify
data:
message: "Your message goes here"
title: "Custom subject"
```
Another common notification integration is via the companion app for Android or iPhone. This can be chosen with the action "Send a notification via mobile_app_your_phone_name" which uses the service `notify.mobile_app_your_phone_name`. See the [companion app documentation](https://companion.home-assistant.io/docs/notifications/notifications-basic) for lots of customization options.
With any of these integrations, the `message` data input in the automation editor is the main text that will be sent. Other fields are optional, and some integrations support additional `data` or `target` information to customize the action. For more details, refer to their integration documentation.
Be aware that the `notify.notify` service is shorthand for the first notify service the system can find. It might not work as intended. Choose a specific service to make sure your message goes to the right place.
Notifications can also be sent using [Notify groups](https://www.home-assistant.io/integrations/group/#notify-groups). These allow you to send notification to multiple devices with a single call, or to update which device is notified by only changing it in a single place.
### Test if it works
After you setup a [notifier](/integrations/#notifications) a simple way to test if you have set up your notify platform correctly, is to open **Developer Tools** from the sidebar and then select the **Services** tab. Choose your service from the **Service** dropdown menu, enter the sample below into the **Service Data** field, and press the **CALL SERVICE** button.
After you setup a [notifier](/integrations/#notifications), a simple way to test if you have set up your notify platform correctly is to open {% my developer_services title="**Developer tools** > **Services**" %}** tab from the sidebar. Choose your service from the **Service** dropdown menu depending on the integration you want to test, such as **Notifications: Send a persistent notification** or **Notifications: Send a notification via mobile_app_your_phone_name**. Enter your message into the **message** field, and select the **CALL SERVICE** button.
### Examples
In the **Developer Tools**, on the **Services** tab, select the **Notifications: Send a persistent notification** action. Enter a message and test sending it.
If you switch to view the YAML data under **Developer Tools**, it will appear as below. The same {% term action %} can be chosen in {% term automation %} actions %, whose YAML will appear the same:
{% raw %}
```json
{
"message": "The sun is {% if is_state('sun.sun', 'above_horizon') %}up{% else %}down{% endif %}!"
}
```yaml
service: notify.persistent_notification
data:
message: "Can you hear me now?"
```
{% endraw %}
The automation equivalent would be:
The notify integration supports specifying [templates](/docs/configuration/templating/). This will allow you to use the current state of entities in Home Assistant in your notifications, or use more complex logic to decide the message that is sent.
{% raw %}
```yaml
action:
service: notify.notify
service: notify.persistent_notification
data:
message: "You have {{ states('todo.shopping_list') }} items on your shopping list."
```
{% endraw %}
{% raw %}
```yaml
action:
service: notify.persistent_notification
data:
message: "The sun is {% if is_state('sun.sun', 'above_horizon') %}up{% else %}down{% endif %}!"
```
{% endraw %}