Designing Your Notifications

Designing Your Notifications

An alerting system lives or dies by its notifications. Too few, and things are missed; too many, and people start ignoring them, and then things are missed anyway. This page is about getting the balance right: who's told, how loudly, how often, and what they can do about it.

Notifier groups: who is told

Alerts send to notifier groups, never to phones or speakers directly. A group is a set of destinations:

• Notify entities (notify.* entities): get the message and, if they can show one, the title.
• Legacy notify actions, such as notify.mobile_app_alices_phone: can take extra Data (a notification channel, an image, a sound) and a Target, and on the mobile app get the full treatment (below).
• A persistent notification in Home Assistant itself.

Think of groups as channels, not people. A good starting set is the one in Getting Started:

Group	Members	Loud?	Used by
Phone	everyone's mobile app action	no	the defaults
Persistent	a persistent notification	no	the defaults
Speakers	smart speakers or TTS	yes	alerts that should be heard in the house

Set Phone and Persistent as the default groups in the options. Most alerts use the defaults; the important ones choose their own groups (adding Speakers); some choose fewer (Phone only), or none at all, for alerts that should only show on the card.

Other groups people find useful:

• One person: just Bob's phone, for alerts that are his to deal with (the server room, if Bob is the one who fixes it).
• Phone with camera: a mobile app action with Data image: /api/camera_proxy/camera.front_door, for doorbell and motion alerts.
• Neighbour: for escalations when nobody in the house responds.
• TV: a notify action that pops a message up on the television.

The group is where per-destination settings live (data, channels, quiet hours), so the same alert can reach a phone, a speaker, and a TV, each in its own way.

Priorities: how urgent

Priority	Use it for	What it does
Emergency	Danger to people or property, now: smoke, a major leak, an ignored critical alert	Top of the card, glowing and pulsing. Through quiet hours. iPhone: critical (through silent mode and Do Not Disturb).
Critical	Needs action soon: a leak, an unarmed alarm, a bridge down	Glowing on the card. Through quiet hours. iPhone: time-sensitive (through a Focus).
Warning	Needs attention: a door left open, a freezer warming	Caution stripes on the card. Through quiet hours (the default threshold).
Notice	Worth knowing: laundry done, a door open	Held by loud groups during quiet hours.
Informational	Status and chores: bins, batteries, modes	Held by loud groups during quiet hours. Bottom of the card.

Be stingy with Emergency and Critical. If everything is urgent, nothing is.

Messages: what they say

Every alert has four messages, all templates:

Message	Sent	Default
On message	when it starts firing	"{{ name }} is firing."
Card message	(shown on the card instead of the on message)	the on message
Reminder message	on its reminder schedule	"{{ name }} is still firing ({{ duration }})."
Done message	when it stops	"{{ name }} stopped firing after {{ duration }}."

The defaults are deliberately generic. Give real alerts real messages: what's wrong, and if it isn't obvious, what to do. Useful variables:

Variable	Is
name, entity_id, priority	the alert's
subject_entity_name, subject_entity_id	what the alert is about
duration, duration_seconds	how long it's been firing ("1 hour 5 minutes"); while latched, how long ago it stopped
fire_count	how many times it has fired (manual and event alerts can fire again)
fire_data	the data a manual alert was fired with
trigger	trigger and bus event alerts: the trigger's variables
reason	on, reminder, or done, for one template that serves all three
end_reason	in the done message: resolved, dismissed, no_data, or disabled
latched	true in a latched alert's reminders and done message
target, target_name	generated alerts: the target entity

Plus anything a Home Assistant template can do: states('sensor.x'), expand('group.x'), and so on. The card's messages update as the entities they read change: Alarm not armed while away lists open doors, and the list shrinks as you close them.

A done message that knows why it ended:

{% if end_reason == 'no_data' %}Lost contact with {{ subject_entity_name }}.
{% elif end_reason == 'disabled' %}{{ name }} was turned off.
{% else %}{{ subject_entity_name }} is back to normal.{% endif %}

Reminders: how often

Reminders follow a schedule: minutes between reminders, where the last gap repeats. The default, 10, 20, 30, 60, reminds at 10, 30, and 60 minutes, then hourly. Reminders stop when someone acknowledges the alert, and resume (on the original schedule) if the acknowledgement is removed or a snooze runs out.

Some schedules that work:

Schedule	For
2 or 5	Emergencies and leaks: every few minutes until someone responds.
10, 20, 30, 60	The default: most things.
30	Low-urgency things worth nagging about.
60	Chores.
1440	Maintenance: once a day.
(empty)	No reminders: the on message is enough, or it's card-only.

Rather than a very short schedule, consider an escalation: normal reminders, and a second alert that's louder if nobody has responded in 15 minutes.

Quiet hours: when

Quiet hours hold back notifications to loud groups (speakers, TTS) for less important alerts while a quiet-hours entity is on. Set them in the options: an entity (a Schedule helper from 22:30 to 07:00, or an input_boolean your bedtime routine turns on) and a threshold (Warning by default: Notice and Informational are held; Warning and above get through).

Each loud group either:

• Holds (the default): nothing is sent until quiet hours end. Then each alert that's still firing and unacknowledged gets one reminder, and those that came and went overnight are listed in one Quiet hours summary per group.
• Softens: sends anyway, but with each member's Quiet-hours data in place of its Data. For a speaker, a lower volume; for a phone, a silent channel.

Quiet groups (phones, persistent notifications) are never affected: a phone has its own do-not-disturb. A loud group can also have its own quiet-hours entity and threshold: the nursery speaker can be quiet from 7 p.m.

Example: a phone that rings loudly, except at night. A group Phone (loud) with Loud on and During quiet hours Soften, whose mobile app member has:

Data	push: {sound: {name: default, critical: 1, volume: 1.0}}
Quiet-hours data	push: {interruption-level: passive}

By day, its alerts ring at full volume. During quiet hours, alerts below the threshold arrive silently, to be found in the morning, and alerts at or above it still ring.

Throttling: not too much

An alert that flaps (fires and ends, fires and ends) can flood your phone. Throttling limits it to so many on notifications in so many minutes. The one that reaches the limit is marked "[Throttling starts]", the rest are held, and when the rate drops, one summary says what happened ("[Throttling ends] Fired 7× while throttled…"). The alert's state isn't affected, only its notifications.

Set a default throttle in the options (none by default), or per alert. Example: Errors in the log, at most 3 in 60 minutes.

Throttling treats the symptom. If the condition flickers (a sensor bouncing between open and closed), fix that with a delay before ending, which stops the alert ending at all for a brief flicker.

On the phone: replacing, clearing, buttons

With the Home Assistant companion app (notify.mobile_app_* actions), each alert's notifications behave like one notification:

• A reminder replaces the on message, and the done message replaces the last reminder: one notification per alert, not a pile.
• When the alert is acknowledged (anywhere, by anyone), its notification is cleared from every phone.
• Notifications carry buttons: the alert's own, then Acknowledge and Snooze Alert (for alerts that can be acknowledged). Android shows only three, so the alert's own come first.

Per member, you can keep the notification when acknowledged, or clear it when the alert ends instead of showing the done message. A legacy action that isn't notify.mobile_app_* but reaches phones (a notify group of them) can have these features turned on with Mobile app features. Notify entities can't replace or clear: each notification arrives separately.

Custom buttons

An alert's Notification buttons each have a label and an action (any action sequence, as in a script). They're on the phone notification and the card. Tapping one runs that action, as the person who tapped it, even after the alert has stopped. Ideas:

Alert	Button
Garage door left open	Close door: cover.close_cover
Water leak	Shut off water: valve.close_valve
Hotplate left on	Turn off: switch.turn_off
Bathroom humid	Fan on: fan.turn_on
Filter due	Filter changed: input_datetime.set_datetime
Medication	Taken: input_boolean.turn_on
Front door unlocked	Lock it: lock.lock

Turn on Only from an unlocked phone (iOS) for anything security-sensitive: iOS then asks for Face ID or the passcode first, and the card asks for confirmation. A button that unlocks or opens something should always have it.

An automation can press a button too: alert_redux.press_button with the label.

The Snooze Alert button snoozes for the alert's Snooze button duration, or the default from the options (1 hour). (It's not the same as the phone's own snooze for a notification, which only hides the notification.)

iPhone interruption levels

On an iPhone, Emergency alerts' on and reminder notifications are sent as critical (through silent mode and Do Not Disturb; allow Critical Alerts for the app in iOS settings), and Critical alerts' as time-sensitive (through a Focus). There's no setting for this. To pin a phone to one level whatever the priority, give its member Data push: {interruption-level: active}.

When something fails

A notifier that's missing (its integration hasn't loaded yet) or fails is retried for up to 5 minutes (the retry timeout), surviving a restart. If a notification reaches nobody in its groups, it goes to the fallback group (a persistent notification, unless you choose a group). A legacy notify action that doesn't exist is raised as a Repairs issue naming its group.

A checklist

• Does every alert have a real on message, saying what's wrong?
• Is Emergency kept for real emergencies?
• Do alerts that need action have a button that takes it?
• Does anything flap? Add a delay before ending, or a throttle.
• Is anything loud allowed to wake you that shouldn't? Check the quiet-hours threshold.
• If someone ignores an important alert, does anything escalate?
• Do the alerts that matter after they stop keep until acknowledged?