Introduction
The mobile_app
notify platform accepts the standard title
, message
and target
parameters used by the notify platform. The mobile_app notify platform supports targets as services. As long as you granted notifications permissions during setup, you will find all your devices listed as targets for the notify service with names prefixed notify.mobile_app_
followed by the Device ID of you device. This can be checked in the App Configuration menu of the sidebar and defaults to the name specified in the General>About within the iOS settings app or under About>Phone in Android settings (with spaces and non alphanumeric characters replaced by underscores). A requirement of the notify platform is that you must specify at least message:
in your payload. A minimum working example of a notification is:
The mobile_app platform provides many enhancements to the simple notification generated above. The image below, for example, shows an iOS actionable notification allowing you to trigger different automations from each button.
#
Enhancing basic notifications#
Including Links
If you include a URL in your notification, tapping on the notification will open that URL. You may use external or internal (relative) URL's. The below example sends a notification that when tapped will open the Home Assistant app into a Lovelace view of your cameras.
URL's can alternatively be included in the message:
portion of your notification.
You can change which iOS browser notifications open in under App Configuration -> General and can turn off the confirmation prompt under App Configuration -> Notifications.
Android users can achieve this through the use of actionable notifications or click action.
#
Notification Sounds
By default the default iOS notification sound (Tri-tone) will be played upon receiving a notification. See the Sounds documentation for details of the available sounds and how to add custom sounds. The default notification sounds (Tri-tone) can be disabled by setting sound
to none
in the data payload:
#
Badge
You can set the app icon badge in the payload. The below example will make the app icon badge say 5:
By setting the message to delete_alert
you can silently update the app badge icon in the background without sending a notification to your phone.
#
Subtitle
A subtitle is supported in addition to the title:
#
Thread-id (grouping notifications)
Grouping of notifications is supported on iOS 12 and above. All notifications with the same thread-id will be grouped together in the notification center. Without a thread-id, all notifications from the app will be placed in a single group.
For Android we will need to use the group
property in order to group the notifications together and declutter the notification pull-down.
#
Replacing notifications
Existing notifications can be replaced using apns-collapse-id
. This will continue to send you notifications but replace an existing one with that same apns-collapse-id
. When sending consecutive messages with the same apns-collapse-id
to the same device, only the most recent will be shown. This is especially useful for motion and door sensor notifications.
For Android users you can easily replace the notification using the tag
service data.
You can also remove a notification by sending clear_notification
to the same tag
#
Sending notifications to multiple devices and Â
To send notifications to multiple devices, create a notification group:
Now, you can send notifications to everyone in the group using. If you plan to group Android and iOS devices only message
and title
will work:
#
Controlling how a notification is displayed when in the foreground
By default, if the app is open (in the foreground) when a notification arrives, it will display the same as when the app is not active (in the background), with a visual alert showing notification contents, a badge update (if one was sent in the notification) and the sound of your choice. You can control how a notification is displayed when the app is in the foreground by setting the presentation_options
string array. Allowed values are alert
, badge
and sound
.
#
Notification Color
In Android you can set the color
of the notification, you can use either the color name or the hex code.
#
Sticky Notification
You can set whether to dismiss the notification upon selecting it or not. Setting sticky
to 'true'
will keep the notification from being dismissed when the user selects it. Setting it to 'false'
(default) will dismiss the notification upon selecting it.
#
Notification Click Action
When a notification is selected the user can either be navigated to a another application, a specific lovelace view/dashboard, or you can have a webpage open to any URL. 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 would like to have another application open then format is app://<package name>
where <package name>
is replaced with the actual package you wish to open. The default behavior is to just open the Home Assistant app and load the default dashboard.
#
Notification Channels
Notification channels allows users to separate their notifications easily (i.e. alarm vs laundry) so they can customize aspects like what type of sound is made and a lot of other device specific features. Devices running Android 8.0+ are able to create and manage notification channels on the fly using automations. Once a channel is created you can navigate to your notification settings and you will find the newly created channel, from there you can customize the behavior based on what your device allows.
#
Creating a channelIn order to create a notification you will need to specify the channel
you wish to use. By default all notifications use General
if channel
is not defined.
In the example below a new channel will be created with the name Motion
:
Default values for a channel if not provided will be as follows:
- Importance: Default which means Default notification importance: shows everywhere, makes noise, but does not visually intrude.
- Vibration Pattern: Vibration disabled
- LED Color: LED disabled
#
Removing a channelIf you wish to remove a channel you will need to send message: remove_channel
with the channel
you wish to remove.
Removing a channel doesn't reset the settings to the default values, it just removes it from the notification channels list. If you send a notification to a removed channel, it will restore it. The only way to really remove a channel is by clearing the app data which will remove everything.
Depending on when you installed the app you may want to send remove_channel
to channel: default
to clean up the old default channel:
#
Specific channel propertiesinfo
If your device is on Android 8.0+ the following properties will become the default for the channel
the first time they are set:
These options will be ignored once they are set for a particular channel, only lowering of the importance
will work (if the user has not already modified this).
Devices running Android 5.0-7.1.2 do not have channels and do not need to worry about this note.
#
Notification Channel Importance
When you are setting the
channel
for your notification you also have the option to set the importance
for the channel
per notification. Possible values for this property are high
, low
, max
, min
and default
. To learn more about what each value does see the FCM docs. For devices before Android 8.0 this property can be used like priority
with the same options described up above.
See Specific channel properties for important behavior of this property.
#
Notification Vibration Pattern
You can set the vibration pattern for the channel
by setting the vibrationPattern
property. Possible values are a list of numbers. eg. "100, 1000, 100, 1000, 100" etc.. The pattern specification is "off time, on time, off time, on time, off time" etc.
See Specific channel properties for important behavior of this property.
#
Notification LED Color
Some Android devices have a multi-color notification LED. By setting the ledColor
property you can control what color the LED will flash. Possible values are the same as for property color eg '#2DF56D' # or 'red'.
See Specific channel properties for important behavior of this property.
#
Persistent Notification
Persistent notifications are notifications that cannot be dimissed by swiping away. These are useful if you have something important like an alarm being triggered. In order to use this property you must set the tag
property as well. The persistent
property only takes boolean (true/false
) values, with false
being the default. The persistent notification will still be dismissed once selected, to avoid this use sticky: true
so the notification stays.
In the example below we will create a notification and then later on we will remove it.
To remove the persistent notification we send clear_notification
to the tag
that we defined.
#
Notification Subject
If your notification is going to have a lot of text (more than 6 lines) you can opt to show smaller text by setting the subject
.
#
Notification Timeout
You can set how long a notification will be shown on a users device before being removed/dismissed automatically. You may use the timeout
property along with the value in seconds to achieve this.
#
Notification Message HTML Formatting
You can add some custom HTML tags to the message
of your notification.
#
Notification Icon
You can set the icon for a notification by providing the icon_url
. The URL provided must be either publicly accessible or can be a relative path (i.e. /local/icon/icon.png
), more details can be found in attachments. It is important to note that if you set the image
then Android will not show the icon for the notification, the image
will be shown in its place. So the message
will be shown with the image
and with the image as the icon.
#
Text To Speech Notifications
Instead of posting a notification on the device you can instead get your device to speak the notification. This notification works different than the others. You will set message: TTS
and the actual text to speak would be in the title
. Current support is limited to the current Text To Speech locale set on the device. If there is an error processing the message you will see a toast message appear on the device. Check to make sure that the Google Text To Speech engine is up to date and set as the default, in case you run into any issues.
By default Text To Speech notifications use the music stream so they will bypass the ringer mode on the device as long as the device's volume is not set to 0. You have the option of using channel: alarm_stream
to have your notification spoken regardless of music volume.
If you find that your alarm stream volume is too low you can use channel: alarm_stream_max
which will temporarily set the alarm stream volume to the max level, play the notification and then revert back to the original volume level.
You may not want the TTS notification to be spoken in certain situations (e.g. if the Ringer mode is not normal
or DND is enabled). This can be done by adding a condition in your automation that checks the state of other sensors. Few examples are presented below:
#
Chronometer Notifications
You can create notifications with a count up/down timer (chronometer) by passing the chronometer
and when
options. This feature requires at least Android 7.0.
Do note that the notification will not disappear when the timer reaches 0. Instead, it will continue decrementing into negative values. You may want to utilize notification timeouts or replace the notification when the timer hits zero.
- chronometer - true to enable chronometer mode
- when - the timestamp to count up or down to (seconds since 01/01/1970)