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.

Android

CommandDescription
clear_notificationRemoves a notification from the status bar, more details.
command_dndControl Do Not Disturb mode 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.
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.

Do Not Disturb

Android  BETA  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: Notify Mobile app
trigger:
...
action:
service: notify.mobile_app_<your_device_id_here>
data:
message: "command_dnd"
title: "priority_only"

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: Notify Mobile app
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  BETA

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: Notify Mobile app
trigger:
...
action:
service: notify.mobile_app_<your_device_id_here>
data:
message: "command_ringer_mode"
title: "vibrate"