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.
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.
Dynamic actions on watchOS require having the Watch App installed. You can do this in the system Watch app if not already installed.
You can include an
actions array in your service call.
Android allows 3 actions.
allows around 10 actions. Any more and the system UI for actions begins having scrolling issues.
Each action may consist of the following keys:
|Required. The identifier passed back in events||When set to |
|Required. The title of the button shown in the notification|
|Optional. The URL to open when tapped|| Android requires setting the |
All of the following keys are optional.
|None||There are no Android-specific keys at this time.|
All of the following keys are optional.
|Set to ||This is automatically set to |
|Title to use for text input for actions that prompt.|
|Placeholder to use for text input for actions that prompt.|
To navigate to a frontend page, use the format
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/ is replaced by your defined
dashboard URL and
view is replaced by the defined
path within that dashboard. For example:
If you want to open an application you need to set the action to
URI. The format will be
<package> is replaced by the package you wish to open (ex:
app://com.twitter.android). If the device does not have the application installed then the Home Assistant application will open to the default page.
With action set to
URI you can also trigger the More Info panel for any entity. The format will be
<entity_id> is replaced with the entity ID you wish to view. Ex:
You can also use application-launching URLs. For example, to make a telephone call:
Or to launch a page in your default browser:
There are some important things to keep in mind when building actionable notifications:
- Your script or automation could be run multiple times
- The actions for your notification are shared across all notifications
To avoid issues, you can create unique actions for each time your script is run. By combining context and variables, this can be fairly straightforward:
The above sends a notification, waits for a response, and then performs whichever action is being requested. You can control how automations or scripts run when an existing one is already executing by changing the automation mode.
When the notification action is performed, the
mobile_app_notification_action event fires with the following data:
You can also create automations that trigger for any notification action. For example, if you wanted to include a
SILENCE action on a variety of notifications, but only handle it in one place:
Initially upgrading to 2021.5 may require a restart to allow dynamic actions to show up. This will only be necessary once.
Starting in iOS version 2021.5, actions are specified inline with notifications. To migrate, do the following:
- Add the
actionsarray to each notification. For example:
- Convert your event triggers to the new values
In 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.categoryset 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
actionNameproperty of the event
ios.notification_action_fired, along with other metadata such as the device and category name.
- 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.
|required||A friendly name for this category.|
|required||A unique identifier for the category. Must be lowercase and have no special characters or spaces (underscores are ok).|
|required||A list of actions. See below.|
|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.|
|required||The text to display on the button. Keep it short.|
|optional||The mode in which to run the app when the action is performed. Setting this to |
|optional*||The button label. Required if |
|optional||The placeholder text to show in the text input field. Only used if |
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
%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.
Here is an example automation to send a notification with a category in the payload:
If you want to navigate to a Lovelace page or launch an app for a notification, you can use the
To navigate to a dashboard when tapping a notification:
To navigate to a specific dashboard when tapping a notification action:
You can also use application-launching URLs. For example, launch an external website using
https://example.com or make a phone call using
When an action is selected an event named
ios.notification_action_fired will be emitted on the Home Assistant event bus. Below is an example payload:
Here's an example automation for the given payload:
- 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.
For 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.