mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-22 08:46:51 +00:00
clarify notifications building block page (#31803)
* 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:
parent
74549d919e
commit
495b069f20
@ -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 %}
|
||||
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user