Actionable Notifications
Actionable notifications are a unique type of notification as they allow the user to add buttons to the notification which can then send an event to Home Assistant once clicked. This event can then be used in an automation allowing you to perform a wide variety of actions. These notifications can be sent to either iOS or Android but they do have some differences. iOS allows you to attach up to four actions while Android only allows you to attach up to three actions per notification.
Some useful examples of actionable notifications:
- A notification is sent whenever motion is detected in your home while you're away or asleep. A "Sound Alarm" action button is displayed alongside the notification, that when tapped, will sound your burglar alarm.
- Someone rings your front doorbell. You receive a notification with a live camera stream of the visitor outside along with action buttons to lock or unlock your front door.
- Receive a notification whenever your garage door opens with action buttons to open or close the garage.
If you are using iOS please continue to read below, if you are using Android start from the example here.
On iOS notifications can be grouped by category, this allows for different types of notifications from Home Assistant to be placed in a appropriate stacks on the lock screen and even custom summary text to be used on the notification stack. These categories also allow you to create actionable notifications.
#
Overview of how actionable notifications work on iOSIn advance of sending a notification:
- Define a notification category in your Home Assistant configuration which contain 1-4 actions.
- At launch iOS app requests notification categories from Home Assistant (can also be done manually in notification settings).
When sending a notification:
- Send a notification with
data.push.category
set to a pre-defined notification category identifier. - Push notification delivered to device.
- User opens notification.
- Action tapped.
- Identifier of action sent back to HA as the
actionName
property of the eventios.notification_action_fired
, along with other metadata such as the device and category name.

#
Definitions- Category - A category represents a type of notification that the app might receive. Think of it as a unique group of actions.
- Actions - An action consists of a button title and the information that iOS needs to notify the app when the action is selected. You create separate action objects for distinct action your app supports.
#
Category parametersName | Default | Description |
---|---|---|
name: | required | A friendly name for this category. |
identifier: | required | A unique identifier for the category. Must be lowercase and have no special characters or spaces (underscores are ok). |
actions: | required | A list of actions. See below. |
#
Actions parametersName | Default | Description |
---|---|---|
identifier: | required | A unique identifier for this action. Can be entirely either upper or lower case (but should not mix the two) and have no special characters or spaces (underscores are ok). Only needs to be unique to the category, not unique globally. |
title: | required | The text to display on the button. Keep it short. |
activationMode: | optional | The mode in which to run the app when the action is performed. Setting this to foreground will make the app open after selecting. Default value is background . |
authenticationRequired: | optional | If true , the user must unlock the device before the action is performed. |
destructive: | optional | When true , the corresponding button is displayed with a red text color to indicate the action is destructive. |
behavior: | optional | When textInput the system provides a way for the user to enter a text response to be included with the notification. The entered text will be sent back to Home Assistant. Default value is default . |
textInputButtonTitle: | optional* | The button label. Required if behavior is textInput . |
textInputPlaceholder: | optional | The placeholder text to show in the text input field. Only used if behavior is textInput |
Here's a fully built example configuration:
Rather than defining categories using YAML within configuration.yaml
, you can create them directly within the Companion App. This can be done from the Notifications page of the App Configuration Menu (accessed from the sidebar menu).
Two variables are available for use in the Hidden preview placeholder
and Category summary
. %u
will give the total number of notifications which have been sent under the same thread ID (see this document for more details). %@
will give the text specified with summary:
in the push:
section of the notification payload.
#
Building automations for notification actionsHere is an example automation to send a notification with a category in the payload:
Example
For Android you create the action directly in the automation action. The below example will give you 3 actions in your notification. The first action will send back an event with the action alarm
and the second action will open the URL or load a lovelace view/dashboard. If you plan to use a lovelace view the format would be /lovelace/test
where test
is replaced by your defined path
in the defined view. If you plan to use a lovelace dashboard the format would be /lovelace-dashboard/view
where /lovelace-dashboard/
is replaced by your defined dashboard
URL and view
is replaced by the defined path
within that dashboard.
If you want to open an application you need to set the action to URI
. To pick the application to open prefix app://
to the the package name. If the device does not have the application installed then the Home Assistant application will open to the default page.
When an action is selected an event named ios.notification_action_fired
for iOS and mobile_app_notification_action
for Android will be emitted on the Home Assistant event bus. Below is an example payload.
event example
 Android event example
Here's an example automation for the given payload:
Example
 Android Example
Notes:
textInput
will only exist ifbehavior
was set totextInput
.action_data
is a dictionary with parameters passed in theaction_data
dictionary of thepush
dictionary in the original notification.- When adding or updating push categories in
configuration.yaml
be sure to update push settings within the Home Assistant iOS app. This can be found within the Notifications page of the App Configuration menu (accessed from the sidebar menu). You may have to exit the Notifications page and reopen it before new categories are shown. If they are still not listed, restart the Home Assistant Companion App.
#
Compatibility with different devicesSpecific
#
iOS 13 and later- All devices support notification expanding by performing a right to left swipe and pressing 'View' in the lock screen or pressing and holding, but on 3D Touch-enabled devices you may still need to apply some force to do it. If you're not in the lock screen, you can also pull the notification down to expand it.
#
Prior to iOS 13For devices that support 3D Touch - a firm press on the notification will expand it, showing the action buttons underneath. Supported devices include the iPhone 6S, iPhone 6S Plus, iPhone 7, iPhone 7 Plus, iPhone 8, iPhone 8 Plus, iPhone X, iPhone XS and iPhone XS Max. If not in lock screen, you can also pull the notification down to expand it.
For devices that do not support "3D Touch" (such as the iPhone 6 and below, iPhone SE, iPhone XR and iPads), you perform a left to right swipe on the notification, then tap on the 'View' button. This will expand the notification and show the relevant action buttons underneath. If not in lock screen, you need to pull the notification down to expand it.