Skip to main content

Notification Commands

The Companion apps offer a lot of different notification options. In place of posting an actual notification on the device you can instead send a command as the message to trigger certain actions on your phone. Read below to find out what commands are supported on each platform.

iOS

CommandDescription
request_location_updateRequest a location update from the device, see below for implications about this command.
clear_badgeSilently removes the badge from the App icon without displaying a notification.
clear_notificationRemoves a notification, more details.
update_complicationsUpdates the complications on a paired Apple Watch. More details.

Android

CommandDescription
clear_notificationRemoves a notification from the status bar, more details.
command_activityLaunch an activity with a specified URI to any app, more details and use cases below.
command_bluetoothTurn bluetooth on or off.
command_ble_transmitterTurn BLE beacon transmitter on or off.
command_broadcast_intentSend a broadcast intent to another app, see below for how it works and whats required.
command_dndControl Do Not Disturb mode on the device, see below for how it works and whats required.
command_high_accuracy_modeControl the high accuracy mode of the background location sensor, see below for how it works and whats required.
command_mediaControl media playing on the device, see below for how it works and whats required.
command_ringer_modeControl the ringer mode on the device, see below for how it works and whats required.
command_screen_onTurn on the device screen.
command_volume_levelControl the volume for all available audio streams, see below for how it works and whats required.
command_webviewOpen the app to the homepage or any dashboard or view, see below for how.
remove_channelRemove a notification channel from the device settings, more details.
request_location_updateRequest a location update from the device, see below for implications about this command.

Activity#

Android

On Android you can send message: command_activity to launch any activity. This command requires a specific permission that the app is unable to prompt or auto-accept. Instead by sending the command for the first time the app will launch an activity allowing the user to enable Home Assistant access to the devices Display over other apps Policy. This is required in order for the app to gain control of this setting.

The tag parameter will need to be set to the Intent Action string, or the notification will post as normal. If the activity requires a URI then you will need set that as the title, otherwise the notification will post as normal. channel can be set to the package of where the activity is to be launched, otherwise Android will make a best effort to pick a default. If the package cannot be found then the notification will post as normal. You must know the intending URI (if required), action and package to start the activity. Typically this will be a documented feature if supported by the app.

Extras are also supported under the group parameter. As there can be any number of extras added to the intent we will need to split each extra by a comma ,. Then each extra name and value needs to be separated by a colon :. Please refer to the example in Broadcast Intent to see the proper format.

subject can also be set to the MIME type if you need to set it. You will need to know the MIME type string if the activity requires it.

The below example follows Google's documentation to show you how this feature works by launching Google Maps Navigation.

Example:

automation:
- alias: Navigate
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_activity"
title: "google.navigation:q=arbys"
data:
channel: "com.google.android.apps.maps"
tag: "android.intent.action.VIEW"

To continue with the above example you can also launch search results with the following:

automation:
- alias: Search google maps
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_activity"
title: "geo:0,0?q=1600+Amphitheatre+Parkway%2C+CA"
data:
channel: "com.google.android.apps.maps"
tag: "android.intent.action.VIEW"

BLE Beacon Transmitter#

Android

Users can turn the iBeacon transmitter on or off using message: command_ble_transmitter with the title being either turn_off or turn_on. If title is blank, not set or not one of the above expected values then the notification will post as normal.

Example:

automation:
- alias: Turn off BLE transmitter
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_ble_transmitter"
title: "turn_off"

Bluetooth#

Android

Users can turn Bluetooth on or off using message: command_bluetooth with the title being either turn_off or turn_on. If title is blank, not set or not one of the above expected values then the notification will post as normal.

Example:

automation:
- alias: Command bluetooth
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_bluetooth"
title: "turn_off"

Broadcast Intent#

Android

Using notification commands you are now able to send a broadcast intent to another app in order to control that app based on the intent. Not all apps support intents and if they do they may document it for users to control. You must set message: command_broadcast_intent and the title must contain the intent action while channel must contain the package the intent is for. The package name and action are provided by the app you wish to send the intent to. If an invalid format is sent you may either see a notification or a toast message.

Example:

automation:
- alias: Send broadcast intent
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_broadcast_intent"
title: "action"
data:
channel: "package-name"

An example of an application that accepts broadcast intents is Sleep as Android. To start a sleep tracking event the format would be as follows:

automation:
- alias: Send broadcast intent to start sleep tracking
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_broadcast_intent"
title: "com.urbandroid.sleep.alarmclock.START_SLEEP_TRACK"
data:
channel: "com.urbandroid.sleep"

Extras are also supported under the group parameter. As there can be any number of extras added to the intent we will need to split each extra by a comma ,. Then each extra name and value needs to be separated by a colon :. The below example shows you how to turn on an alarm labeled work in the Sleep as Android application. In this example there are 2 extras being added to the intent.

automation:
- alias: Send broadcast intent with extras
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_broadcast_intent"
title: "com.urbandroid.sleep.alarmclock.ALARM_STATE_CHANGE"
data:
channel: "com.urbandroid.sleep"
group: "alarm_label:work,alarm_enabled:false"

Do Not Disturb#

Android  Android 6+ only

On Android you can send message: command_dnd that you can use to control the state of Do Not Disturb on the device. This command requires a specific permission that the app is unable to prompt or auto-accept. Instead by sending the command for the first time the app will launch an activity allowing the user to enable Home Assistant access to the devices Notification Policy. This is required in order for the app to gain control of this setting.

In addition to sending the message you must also provide the state of Do Not Disturb that you wish to set as the title, see the table below for what is accepted. If the title does not match one of the listed commands then the notification will post as normal and the command will not process. This command is only available for users on Android 6+, users on lower versions will see the notification just like any other.


titleDescription
alarms_onlyAlarms only interruption filter - all notifications except those in the alarm category are suppressed. Some audio streams are muted.
offNormal interruption filter - no notifications are suppressed.
priority_onlyPriority interruption filter - all notifications are suppressed except those that match the priority criteria. Some audio streams are muted.
total_silenceNo interruptions filter - all notifications are suppressed and all audio streams (except those used for phone calls) and vibrations are muted.
Anything elseThe notification will post as a normal notification and the command will not process.

automation:
- alias: Command do not disturb
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_dnd"
title: "priority_only"

High accuracy mode#

Android

Users can turn the high accuracy mode of the background location sensor on or off using message: command_high_accuracy_mode with the title being either turn_off or turn_on. If title is blank, not set or not one of the above expected values then the notification will post as normal.

Example:

automation:
- alias: Turn off high accuracy mode
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_high_accuracy_mode"
title: "turn_off"

Media#

Android

Users are able to control any active media session on their devices. You must set message: command_media and the title must be one from the list below. The channel must be set to the package name you wish to control. The notification will post as normal if one of the required fields is left blank, has incorrect data or a media session is not active.

List of accepted title media commands:

  • fast_forward
  • next
  • pause
  • play
  • play_pause
  • previous
  • rewind
  • stop

Example:

automation:
- alias: Pause spotify
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_media"
title: "pause"
data:
channel: "com.spotify.music"

Request Location Updates#

Android iOS

caution

Do not rely on this functionality due to the time limitations mentioned below.

You can force a device to attempt to report its location by sending a special notification. The notification is not visible to the device owner and only works when the app is running or in the background. On success the sensor.last_update_trigger will change to "Push Notification".

automation:
- alias: Request location update
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "request_location_update"

Assuming the device receives the notification, it will attempt to get a location update within 5 seconds and report it to Home Assistant. This is a little bit hit or miss since Apple imposes a maximum time allowed for the app to work with the notification and location updates sometimes take longer than usual due to factors such as waiting for GPS acquisition.

danger

While it is possible to create an automation in Home Assistant to call this service regularly to update sensors, this is not recommended as doing this too frequently may have a negative impact on your device's battery life and health.

Ringer Mode#

Android

On Android you can control the devices ringer mode by sending message: command_ringer_mode with an appropriate title as outlined in the table below. Certain devices will need to grant a special permission that will appear upon the first command received if the permission was not already granted. This is the same permission as Do Not Disturb up above. If the device has Do Not Disturb enabled then setting to normal or vibrate will turn it off. If the device does not have Do Not Disturb enabled then silent will turn it on.

titleDescription
normalSet the device to normal ringer mode, will turn off Do Not Disturb if enabled and supported.
silentSet the device to silent ringer mode, will turn on Do Not Disturb if disabled and supported.
vibrateSet the device to vibrate ringer mode, will turn off Do Not Disturb if enabled and supported.
Anything elseThe notification will post as a normal notification and the command will not process.

automation:
- alias: Command ringer mode
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_ringer_mode"
title: "vibrate"

Screen On#

Android

On Android you can turn on the screen using a notification by simply sending message: command_screen_on. This will not remove or disable any lock screens you have setup on the device. The reason behind this is the risk associated with the app being unable to set the device policy back (app crash) or if the device requires the policy to be setup again after being removed. All of which is out of the app's control. You may want to adjust the screen timeout setting on your device to control when the screen will turn back off.

automation:
- alias: Screen on
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_screen_on"

Volume Level#

Android

On Android you can control the devices volume level by sending message: command_volume_level with an appropriate title that must be a number. If title is larger than the maximum level then the maximum level will be used or if title is less than 0 then we will default to 0, anything else will result in the notification posting to the device. channel is also required as outlined in the table below. Certain devices will need to grant a special permission that will appear upon the first command received if the permission was not already granted. This is the same permission as Do Not Disturb up above. Changing the volume level will have a direct impact on Do Not Disturb and Ringer Modes, behavior will vary from device to device.

channelDescription
alarm_streamSet the volume level for the alarm stream.
music_streamSet the volume level for the music stream.
notification_streamSet the volume level for the notification stream.
ring_streamSet the volume level for the ring stream.
Anything elseThe notification will post as a normal notification and the command will not process.

automation:
- alias: Command volume level
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_volume_level"
title: 20
data:
channel: "music_stream"

Webview#

Android

If you want to just open the Companion app to any page or even the homepage you will want to send message: command_webview. If you wish to navigate to a specific view or dashboard you will want to use title to specify the path (example: /lovelace/settings). If title is not provided the user will be directed to the homepage. The first time you send this command you will be taken to a permission screen to grant the app access to display over other apps policy. This permission is necessary for the feature to work in the background and we cannot prompt the user to grant it.

Example:

automation:
- alias: Open android webview
trigger:
...
action:
- service: notify.mobile_app_<your_device_id_here>
data:
message: "command_webview"
title: "/lovelace/settings"