Home Assistant can send alerts in three main ways. A push notification goes to your phone through the Companion app. A persistent notification appears in the notifications panel inside Home Assistant. An Alexa announcement is spoken on an Echo device through a community integration. Push notifications can also carry buttons that trigger an automation when tapped. These are usually called actionable notifications.
Send a basic push notification
Push notifications use the notify action for your phone, named notify.mobile_app_<device_name>. To find the exact name, open Developer Tools > Actions and search for mobile_app.
actions:
- action: notify.mobile_app_your_phone
data:
title: "Front door"
message: "The front door has been open for 5 minutes."
Add action buttons and handle taps
Actionable notifications have two halves. The notification sends buttons, each with an ID and a label. A separate automation listens for the tap.
Send the notification with a button:
actions:
- action: notify.mobile_app_your_phone
data:
title: "Garage door open"
message: "The garage door has been open for 30 minutes."
data:
actions:
- action: CLOSE_GARAGE
title: "Close garage"
Handle the tap in an automation:
automation:
- alias: "Close garage from notification"
triggers:
- trigger: event
event_type: mobile_app_notification_action
event_data:
action: CLOSE_GARAGE
actions:
- action: cover.close_cover
target:
entity_id: cover.garage_door
A button does nothing without a matching trigger. Give each button an ID that is specific to its alert, so a tap is matched only to the automation you intended.
Think about what a button does before you add it. A button that acknowledges an alert is low risk. A button that opens or closes a door needs more care. Lock-screen notifications can be read by anyone who picks up the phone, so keep sensitive detail out of the message text.
Platform limits and text replies
- Android shows up to three action buttons per notification.
- iOS and macOS allow more buttons.
- For a typed reply, iOS uses
behavior: textInputon a button. Android uses a separate reply action. The typed text arrives with the event asreply_text. Check the Companion app documentation for the exact setup on each platform.
Replace or clear a notification
Give related notifications the same tag. A new notification with that tag replaces the old one. To remove it, send a message named clear_notification with the same tag:
actions:
- action: notify.mobile_app_your_phone
data:
message: "Washer finished"
data:
tag: laundry
actions:
- action: notify.mobile_app_your_phone
data:
message: clear_notification
data:
tag: laundry
Urgent alerts
Phones can hide or silence alerts, so the Companion app offers settings that make a notification more prominent.
- On Android,
ttl: 0andpriority: highask for immediate, high-priority delivery. Notification channels control how an alert sounds. Their exact keys are in the Companion app documentation. - On iOS, critical alerts need the user to allow them for the app in the phone’s settings.
These settings help, but they are not guaranteed. Do not rely on push alone for smoke or carbon monoxide alarms. Delivery can be delayed, and a phone can be off or out of range.
Persistent notifications
A persistent notification appears in the notifications panel in the Home Assistant sidebar, under the bell icon. It stays there until someone dismisses it or an automation updates or dismisses it. It does not reach your phone.
actions:
- action: persistent_notification.create
data:
title: "Laundry"
message: "The washer has finished."
notification_id: laundry_done
Reusing a notification_id updates the existing notification instead of adding a new one. To remove it:
actions:
- action: persistent_notification.dismiss
data:
notification_id: laundry_done
Use persistent notifications for information that someone will check on a screen at home. For alerts that must reach a person away from home, use push.
Alexa announcements and prompts
Home Assistant’s core setup does not include announcements to Echo devices. Two community routes exist, and both need more maintenance than core features.
Alexa Media Player, installed through HACS, adds notify.alexa_media_<device> actions. Its type option picks the delivery style, such as announce, tts or push.
actions:
- action: notify.alexa_media_kitchen_echo
data:
message: "Dinner is ready"
data:
type: announce
Alexa Media Player is unofficial. Amazon can change its API and break it, so check the service name on your system before you copy this example.
Alexa actionable notifications, where the speaker prompts for a response, rely on a community-built custom Alexa skill and an AWS Lambda function. Expect a more involved setup, and follow the guide that matches the version you run.
The Nabu Casa Alexa integration controls devices by voice. It does not add announcements or actionable prompts.
Choosing a notification type
| Push | Persistent | Alexa announcement | |
|---|---|---|---|
| Reaches your phone | Yes | No | No |
| Can include buttons | Yes | No | Only through community prompts |
| Setup | Companion app | None | HACS integration |
| Support | Core | Core | Community |
Community blueprints can set up notification automations for you. Review the YAML first, as described in that guide. If a button’s automation never runs, see our troubleshooting guide. For the action and trigger basics behind these examples, see the automations and actions guide.