Actionable Notifications: Buttons in a Notification
In Lesson 8 you learned to design good notifications. Now we'll add buttons to them, letting you react straight from the alert without opening the app. That's convenient, but it calls for caution, because a button in a notification is a one-tap decision.
An actionable notification is an alert with one or more buttons underneath it. Instead of just reading "the washer finished," you can tap "Mark as done" right away. Instead of just seeing "window open," you can tap "Remind me in an hour." The phone becomes not just a screen for information, but a place for quick reactions too.
Plan on about fifty-five to sixty-five minutes. First we'll design safe buttons, then we'll actually build them: sending actions, receiving the mobile_app_notification_action event, and saving a confirmation to a helper.
This lesson's core rule
A button in a notification is a fast decision.
It can't do anything risky without a moment's thought.
What an action in a notification is
A plain notification just informs. An actionable notification adds buttons that trigger something when you tap them. The Companion App then sends Home Assistant a signal that you chose a given button, and Home Assistant can react to that: closing a reminder, setting a timer, or recording that something got done.
A button is a shortcut, not magic
An action in a notification doesn't do anything Home Assistant couldn't do another way. It's just a convenient shortcut for reacting straight from the lock screen or the notification shade.
What happens after you tap the button
A button in a notification doesn't magically perform the whole action by itself. After you tap it, the phone sends Home Assistant a piece of information: the user tapped a specific button. Only then can Home Assistant react to that information, say, by triggering an automation, saving a decision, or opening a chosen view.
| Step | What happens |
|---|---|
| 1 | Home Assistant sends a notification with a button. |
| 2 | The phone shows the notification and the available actions. |
| 3 | The user taps a button, say, Remind me later. |
| 4 | Home Assistant receives the tap event and can run further logic. |
Why this matters
In this lesson you'll first work out which buttons are safe, then run a complete example: sending actions, a URI to a dashboard, and handling the event after a tap. Plan your action identifiers carefully: official documentation warns the handler can fire more than once.
Why a button calls for caution
A button in a notification gets tapped in a split second, often without looking. Sometimes from a pocket, sometimes by mistake, sometimes when someone else unlocks the phone. So the action behind a button should be one where an accidental tap doesn't cause harm.
Gets tapped fast: often reflexively, without reading the full text.
Someone else might tap it: a notification can be visible on the lock screen, so be careful with both the button and the alert's wording for sensitive matters.
Hard to undo: if a button physically opened something, undoing it isn't as simple.
Safe actions to start with
The best first actions are ones that tidy up the notification itself or record your decision, without controlling anything physical in the home. That way, even an accidental tap won't cause harm.
Mark as done: closes the reminder and records that you handled the matter.
Remind me later: postpones the alert by a set time, say, an hour.
Turn off this reminder: tells the system you don't want this specific alert again today.
Show details: opens a dashboard or a view with more information. This is one of the safest actions, since it gives context instead of immediately controlling the home.
Start with actions that have no consequences
If the worst an accidental tap can do is close a reminder or postpone it, you're in safe territory. That's an ideal starting point.
The safest action: show details
One of the best actions to start with is a button that doesn't control anything, it just leads to the right place in Home Assistant. For instance, an alert says a window is open, and the Show Details button opens a dashboard with a view of the home or the room. That gives context without the risk of accidentally performing a dangerous action.
Show first, control second
For things that require judging the situation, it's better to open a dashboard than to immediately perform an action. The user sees the context, then decides.
The button label has to be unambiguous
A button in a notification has little room, but it still has to be understandable. The user should know what will happen after tapping, before they tap. Avoid labels like OK, Yes, Do It, or Action, because they don't say what will actually happen.
Good: Remind in an hour, Open dashboard, Mark as done.
Bad: OK, Yes, Do It, Confirm, if it's unclear exactly what you're confirming.
One or two buttons are enough
A notification isn't a home control panel. If you add too many buttons, the user starts wondering what to tap, or taps the wrong one by accident. At the start, one button is usually enough, two at most.
Good: Remind me later and Show details.
Bad: five buttons that turn the notification into a chaotic remote control.
Risky actions: leave for later
Some actions genuinely control the home or touch on security. Don't attach those to a single button at the start, and some shouldn't be a notification action at all. The key thing here is the asymmetry of consequences.
| Action | Why it's risky | What to do instead |
|---|---|---|
| Open the gate | An accidental tap opens the home to the outside. | At most, only closing the gate, and ideally after checking its state and with proper safeguards. Never open it with one tap. |
| Disarm the alarm | An alert is the wrong moment to turn off security with one gesture. | Leave disarming to the app, with a code, not a notification. |
| Unlock the door | Unlocking with one tap is a serious security risk. | Keep it out of notification actions entirely. |
| Turn off heating in winter | A mistake can leave the house cold for hours. | Control it from the dashboard, where you see the full context. |
The asymmetry rule
If a tap's consequence is hard to undo or touches on security, don't turn it into a notification button. Save the convenience for things that don't break anything if you get it wrong.
Close, don't open
A good rule of thumb: actions that increase security are usually less risky than ones that decrease it. A "Close gate" button is safer than "Open gate," but it should still be used sensibly, ideally after checking the gate's state and with the gate's own safeguards working.
The safer direction: close the gate, mute, confirm everything's fine.
The risky direction: open, unlock, disarm, turn off a safeguard.
Confirmation for higher-stakes actions
If you really must put a higher-consequence action in a notification, it's worth adding a confirmation step. Instead of performing the action right away, a button can first open the app or ask for confirmation, and only then carry out the task. At the start, though, the simplest choice is just not putting actions like that in a notification.
Confirmation is friction, and that's the point
An extra step is deliberately slower. For high-consequence actions, that's an advantage, because it reduces the risk of an accidental tap.
A confirmation reduces the risk of a mistake, but it doesn't turn a phone into a certified security system. If an action touches an alarm, a lock, a gate, or a real risk to people or property, treat it with a lot more caution than an ordinary reminder.
Android and iPhone: small differences
Actions in notifications work on both platforms, but they look and behave a bit differently. You don't need to know the details at the start. It's enough to know that the button layout and how buttons are shown can vary between phones.
Android: action buttons are usually visible directly under the notification.
iPhone: sometimes you need to press and hold or expand the notification to see the actions.
So don't assume every household member will see the button right away. A notification should still make sense even when someone just reads it and doesn't use the action.
A notification has to work without a tap too
Don't assume the user will always tap the button. Sometimes they'll just read the notification, sometimes they'll swipe it away, sometimes the system won't show the actions right away. So the notification itself has to be clear and useful even without the button being used.
A button is an extra, not the foundation
First you design a good notification, the way you learned in Lesson 8. Only then do you add an action that makes reacting easier. Never the other way around.
What can go wrong
You attach a critical action to a button: opening a gate or disarming an alarm with one tap.
You forget about the lock screen: the action could be tapped by someone with access to the phone.
Too many buttons: an alert with five actions overwhelms and raises the chance of a mistake.
You make the outcome depend only on the button: a notification without its action becomes useless if someone doesn't see it.
No confirmation for a serious action: nothing protects against an accidental tap.
An unclear button label: the user sees "OK" or "Yes" but doesn't know exactly what they're tapping.
The button matters more than the text: a notification without a tap gives no information at all.
No context before controlling something: instead of showing a dashboard, you perform the action right away.
You assume every system shows actions the same way: Android and iPhone can present buttons differently.
You treat confirmation as full protection: an extra step helps, but it doesn't solve the risk around an alarm, a lock, or a gate.
Do this now: a safe button in a notification
Actionable notifications require: sending an actions array, giving it an identifier, receiving the mobile_app_notification_action event, filtering for the right identifier, and performing a safe reaction. authenticationRequired may require unlocking the device, depending on the platform.
Sent, received, confirmed
Sending a push doesn't mean a human read it. Only a button tap and the mobile_app_notification_action event confirm the user actually reacted.
1. A URI button: Show details (no home control)
action: notify.mobile_app_marek_phone
data:
title: "Living room window open"
message: "The window has been open for 15 minutes."
data:
actions:
- action: "URI"
title: "Show details"
uri: "/home-dashboard/living-room"First create the input_button.test_notification_with_action and input_boolean.marek_checked_office helpers.
2. A notification with a safe event-based action
alias: "TEST - notification with a safe action"
triggers:
- trigger: state
entity_id: input_button.test_notification_with_action
actions:
- action: notify.mobile_app_marek_phone
data:
title: "Reminder"
message: "Check the temperature in the office."
data:
actions:
- action: "CONFIRM_OFFICE_CHECK"
title: "Confirm"
- action: "URI"
title: "Show office"
uri: "/home-dashboard/office"
mode: single3. Handling the tap
alias: "Marek's phone - handle confirmation"
triggers:
- trigger: event
event_type: mobile_app_notification_action
event_data:
action: "CONFIRM_OFFICE_CHECK"
actions:
- action: input_boolean.turn_on
target:
entity_id: input_boolean.marek_checked_office
mode: singleA test checklist
Send the test, tap Confirm, check the helper. Tap it a second time and watch whether the automation fires again. Check both a locked and an unlocked phone, and the Android/iOS differences in how buttons are shown.
Assignment: build and test one safe action
To do
☐ Create the test helpers and deploy the automations from this lesson.
☐ Send the notification with the Confirm button and the URI button, then tap both.
☐ For each action, check what happens if someone taps it by mistake.
☐ List three actions you're deliberately not attaching to a button.
☐ Mark which actions would need confirmation if you ever added them.
☐ Make sure every notification makes sense even without tapping the action.
☐ Limit the number of buttons in a single alert to one or two.
☐ Give each action a name that immediately says what will happen.
☐ For one notification, plan a Show Details action instead of direct control.
☐ Check whether the notification still makes sense if the user doesn't tap any button.
☐ Note which actions might be visible on the lock screen, and whether their wording reveals too much.
Key takeaways
An action is a button under an alert, it lets you react without opening the app.
A button is a fast decision, it has to be safe even when tapped by accident.
Start with actions that have no consequences, mark as done, remind later, show details.
Close, don't open, actions that increase security are less risky than ones that decrease it.
Keep critical things off buttons, a gate, a lock, and an alarm shouldn't work with one tap.
A button is an extra, the notification has to make sense even when the user doesn't tap any action.
What's next
In Lesson 10 we'll cover critical notifications: flooding, smoke, freezing temperatures, and technical alarms. The rules get stricter there, because alerts like these have to cut through a mute and reach you even at night. We'll also say plainly where Home Assistant's role ends and a certified security system's role begins.
For now you have notifications that don't just inform, but let you react safely too. Convenience, yes, but without handing decisions about the home's security over to a single tap.
