Notifications
The Notify integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] 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 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. It is available as an automatically configured notifier. See its documentation for more details.
Building block integration
This notifications is a building block integration that cannot be added to your Home Assistant directly but is used and provided by other integrations.
A building block integration differs from the typical integration that connects to a device or service. Instead, other integrations that do integrate a device or service into Home Assistant use this notifications building block to provide entities, services, and other functionality that you can use in your automations or dashboards.
If one of your integrations features this building block, this page documents the functionality the notifications building block offers.
The state of a notify entity
The state of a notify entity is the date and time when a message was last sent.
Screenshot showing the state of a notify entity in the developer tools.
In addition, the entity can have the following states:
- Unavailable: The entity is currently unavailable.
- Unknown: The state is not yet known.
Action
The legacy notify platform will expose a generic notify action that can be called to send notifications.
| Data attribute | Optional | Description |
|---|---|---|
message |
no | Body of the notification. |
title |
yes | Title of the notification. |
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. |
Usage
The different Notify integrations you have set up will each show up as a different automation actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] that you can use.
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 notify.persistent_notification action.
Notify action
Integrations can also implement the notify entity platform. Entity platform implementations will replace the legacy notify action in time. There is an entity platform action send_message which allows you to send notification messages to multiple notify entities.
| Data attribute | Optional | Description |
|---|---|---|
message |
no | Body of the notification. |
title |
yes | Title of the notification. |
Companion app notifications
A common notification integration is via the Home Assistant 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 notify.mobile_app_your_phone_name action. Refer to the Companion app documentation 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 action is shorthand for the first notify action the system can find. It might not work as intended. Choose a specific action to make sure your message goes to the right place.
Notifications can also be sent using 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, a simple way to test if you have set up your notify platform correctly is to open Developer tools > Actions** tab from the sidebar. Choose your action from the Action 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 Perform action button.
To test the entity platform action, select the notify.send_message action, and select one or more of entity, device, area, or label. Then, supply a message.
Example with the entity platform notify action
Under Developer Tools > Actions, select the Notifications: Send a notification message action. Select some target entity’s using the entity selectors, 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 actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] can be chosen in automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more]. The YAML will appear the same:
action: notify.send_message
data:
entity_id: notify.my_direct_message_notifier
message: "You have an update!"
title: "Status changed"
The notify integration supports specifying templates. 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.
actions:
action: notify.send_message
data:
entity_id: notify.my_direct_message_notifier
message: "You have {{ states('todo.shopping_list') }} items on your shopping list."
Examples with the legacy notify action
In the Developer Tools, on the Action 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 actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] can be chosen in automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more] actions %, whose YAML will appear the same:
action: notify.persistent_notification
data:
message: "Can you hear me now?"
The notify integration supports specifying templates. 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.
actions:
- action: notify.persistent_notification
data:
message: "You have {{ states('todo.shopping_list') }} items on your shopping list."
actions:
- action: notify.persistent_notification
data:
message: "The sun is {% if is_state('sun.sun', 'above_horizon') %}up{% else %}down{% endif %}!"