Migrate the `mobile_app` to the `notify` platform

[jlpouffier]

Problem statement

The mobile_app integration handles communication with our companion app.
It's the most widely used notification platform and should be a first-class citizen for notification handling, as native notifications are among the most valuable features the companion apps offer.

Sending notifications is very hard for numerous reasons.
Eventually, we want to make notifying someone simple: #14.

Today, it is not possible to notify a person; you need to notify a device/entity.

To allow this easy link between a person and notification-capable devices (your phone, your tablet, your LaMetric clock) in the future, we first need to ensure that the mobile_app integration supports the relatively new notify platform.

Today, the mobile_app integration creates one action for each device, such as notify.mobile_app_jean_loics_iphone.

The goal of the technical enabler would be to migrate this action to a notify entity linked to the mobile_app device.
Notifying the device would then be done via the generic notify.send_message

Once this is done, we will be able to add a link between person and the notify entity, just as we add a link between person and the device_tracker to geolocate you.

Scope & Boundaries

In scope

• The mobile_app integration exposes a notifty entity for each device

Not in scope

• Bigger overhauls of the mobile platform

Foreseen solution

Work is being organized in the epic home-assistant/epics#49

Community signals

Notifications platform is very hard to configure and maintain, we have plenty of feedback around this topic from a while ago.

Risks & open questions

• How to deal with all the advanced notification features the mobile app allows today?

Appetite

As needed - this shouldn't be scoped down too much.

Decision log

Date	Decision	Outcome
27/04	Meeting to agree on basic approach	Epic created and tasks created
06/05	We can release this pending documentation	Released the migration into 2026.5

[TimoPtr]

Just to not forget, the current notification for mobile_apps are used for notification (what is mentioned above to be migrated), but we also use notification to send commands. It should be taken in consideration. My point of view on this is that we should keep the command out of the new notification and build something dedicated for commands so it is much easier for users. Let's avoid porting the commands to the new things to avoid making it too complex.

Commands are quite nice and should be discoverable more, since the only way to know about it today is to go through the companion app doc like this one https://companion.home-assistant.io/docs/notifications/notification-commands?_highlight=flash#flashlight

[jlpouffier]

I 100% agree @TimoPtr
We should make sure we migrate notification fonctionalities but not the rest.
And yes, commands add such massive value - But are so hard to use today

[Hedda]

Today, it is not possible to notify a person; you need to notify a device/entity.

FYI, it is also not possible to notify a group of users that have the mobile app, instead you need notify create ”old style groups” if want to send the same notification multiple devices/entities of the mobile app. Real world use case is having user groups for parents and kids or emergency contacts (to send notifications to groups for parents, kids, or emergency contacts instead of each user seperatly). But today it is not possible to group users IDs, (no way to create groups for persons via the UI). I guess the historical reason for this is that a person's user_id is not treated as an entity ids the same way as devices. It would therefor be great if grouping user_id (a.k.a. iD) as users could be added to the scope. That is, groups for user-account that represent people (i.e. person grouping). That too should add additional value directly related to this. See this feature request discussion for reference:

• https://github.com/orgs/home-assistant/discussions/2556

PS: Someone else previously also posted an indireccly related feature request asking for a people group (i.e. a person group) to both keep track of presence as well as use with notify:

• https://github.com/orgs/home-assistant/discussions/1126

[AuraHerreroRuiz]

My point of view on this is that we should keep the command out of the new notification and build something dedicated for commands so it is much easier for users.

yes, commands add such massive value - But are so hard to use today

I've taken a look at the features of the companion app, and everything that Notification Commands can do, and I think I have an idea for what "something dedicated for commands" could look like.

Notification Commands, specifically those that really do not have much to do with notifications at all, should be migrated into:

• Entities of different domains, as some Notification Commands —taking into account some similarly named accompanying sensors— behave like pseudo-entities.
• Their own different actions, exposed if available for that device.

I think that this would mitigate a lot of the risks with the migration, as not only would it allow to keep the notify implementation focused on notifications as already discussed, but it would also reduce user friction with the breaking change.

Here are my thoughts:

Reasoning

Migrating Notification Commands to entities and multiple actions would allow the current action to be removed entirely, which I feel would be necessary to improve user experience as well, as exposing both the new notify entity, and the old action to still support the Notification Commands would be confusing.

My opinion is that current users of Notification Commands (most likely power users, as they are quite hard to set up), would welcome the breaking change if they were replaced with much easier to use entities and specific actions, as it would be much more practical to access the same functionality, or in the case of the actions, only a change of indentation in yaml if the new actions keep the same parameters as the Notification Commands.

Right now, the mobile_app integration exposes only entities in the binary_sensor and sensor domains. Exposing entities for the functionality Notification Commands provide would make their value as accessible as any other action and functionality of any other device within Home Assistant, making the experience of the mobile_app integration more in line with every other integration.

For commands where exposing an entity doesn't make sense, splitting them as their own action would make them much more discoverable by users creating automations, scripts, etc, rather than bundling all the functionality into a single action that doesn't seem capable of providing said functionality by its name and description provided in the UI.

I think this is feasible considering the sensors and Notification Commands already supported.

Example of an Notification Command that should be migrated to an entity

The companion app provides the command_media Notification Command, and the sensor.phone_name_media_session.

The sensor is an enum that exposes Playing, Paused, Stopped, Buffering, etc, and command_media allows for play, pause, next...

Furthermore, the sensor exposes attributes for all media sessions on the device, including artist, title, album and package name of every media session, while command_media requires the package name of an app to control its media session.

I feel it would be much more intuitive to expose all of this information and functionality through a media_player entity. The package names can be presented as different sources. This is all existing functionality (from the user side, I have not taken a look at the companion app implementation), but migrating it to a media_player entity would allow for much more intuitive use.

It could even allow for more features in the future that Notification Commands could complicate for users, and potentially for developers, for example, such as supporting the MediaRouter API to allow changing the playing media output on the device, and exposing the outputs as media_player sound modes.

Of course, my intent here is not to specifically request a media_player entity, with the features listed above (or at all), but rather showcase that Notification Commands are providing "entity like" functionality along with sensor/binary_sensor entities, which would be more appropriate as actual entities provided by the mobile_app integration.

Table of migrations

Here is a table I compiled with a rough idea of what could replace every Notification Command:

iOS

Notification Command (parameter)	Entity domain/action	Entity category	Notes	Relevant sensor/binary_sensors
request_location_update	button	-		-
clear_badge	-	-	This should become part of the new notify implementation.	-
clear_notification	-	-	This should become part of the new notify implementation.	-
update_complications	button	-		-
update_widgets	button	-		-

Android

Notification Command (parameter)	Entity domain/action	Entity category	Notes	Relevant sensor/binary_sensors
clear_notification	-	-	This should become part of the new notify implementation.	-
command_activity	action	-		-
command_app_lock (app_lock_enabled)	switch	CONFIG		-
command_app_lock (app_lock_timeout)	number	CONFIG		-
command_app_lock (home_bypass_enabled)	switch	CONFIG		-
command_auto_screen_brightness	switch	CONFIG		sensor.screen_brightness (automatic attribute)
command_bluetooth	switch	CONFIG		binary_sensor.bluetooth_state
command_ble_transmitter	switch	CONFIG		sensor.ble_transmitter
command_ble_transmitter (ble_set_advertise_mode)	select	CONFIG		sensor.ble_transmitter
command_ble_transmitter (ble_set_uuid)	text	CONFIG		-
command_ble_transmitter (ble_set_major)	text	CONFIG		-
command_ble_transmitter (ble_set_minor)	text	CONFIG		-
command_ble_transmitter (ble_set_measured_power)	number	CONFIG		sensor.ble_transmitter
command_beacon_monitor	switch	CONFIG		-
command_broadcast_intent	action	-		-
command_dnd	select	CONFIG		sensor.do_not_disturb
command_flashlight	switch	-		-
command_high_accuracy_mode	switch, button?	CONFIG	Support for force_off and force_on, should still exists. Perhaps as buttons for force off and on, that consequently also update the switch and binary sensor.	binary_sensor.high_accuracy_mode
command_launch_app	action	-		-
command_media	media_player	-	receiver device class	sensor.media_session
command_ringer_mode	select	CONFIG		sensor.ringer_mode
command_screen_brightness_level	number	CONFIG	Should be exposed as a percent, with percent as the unit of measurement, not with the current 0-255 8-bit unsigned integer of the command, nor the surprisingly currently unit-less sensor	sensor.screen_brightness
command_screen_off_timeout	number/select?	CONFIG	This one is a bit tricky. It allows to read and set arbitrary values in ms (with minimums and maximums set by manufacturer), but my Pixel says Screen Timeout is "not set" if I don't use the command to set the timeout to any of the durations available in the settings app from a list. If the companion app somehow access that list, a select entity might provide better UX.	sensor.screen_off_timeout
command_screen_on	button	-	The functionality to turn the screen on without showing a notification should be migrated to a button entity.	-
command_screen_on (command: keep_screen_on)	switch	CONFIG	The functionality to toggle the Keep Screen On feature of the Companion App should be migrated to a switch.	-
command_stop_tts	-	-	This should become part of the new notify implementation. For example by repalcing a tts notification using a tag with an empty "tts_text" in data?	-
command_persistent_connection	select	CONFIG		-
command_update_sensors	button	-		-
command_volume_level	number	CONFIG	One number entity per stream	sensor.volume_level_alarm, sensor.volume_level_call, sensor.volume_level_dtmf, sensor.volume_level_music, sensor.volume_level_notification, sensor.volume_level_ring, sensor.volume_level_system
command_wake_word_detection	switch	CONFIG	This entity should be disabled by default, and somehow carry the same warning about battery usage to the user before it can be used.	-
command_webview	action	-		-
remove_channel	-	-	This should become part of the new notify implementation.	-
request_location_update	button	-		-

All of these could be split into their own epics and tasks just like #2

[tr4nt0r]

The initial step of adding notify entities should be the easiest part imho.

I've already implemented in ntfy and html5 an approach that I would also suggest for mobile_app. These integrations have specialized actions, that have support for the integration-specific parameters. Having such an action for mobile_app, for example mobile_app.send_message, should make it a lot easier to modify for example the appearance of a notification.

[TheFes]

I'm really looking forward to having notify entities for mobile app. 🥳

I think what @tr4nt0r proposes above is similar as telegram uses as well.
Simple notifications can be sent using notify.send_message to targeting the telegram notify entity. This can only contain title/message.
More advanced config can be done using telegram_bot actions (e.g. telegram_bot.send_message`). This can contain data like which markup language to use. The notify entity can be used as a target for these messages.

So I would think the same setup can be used for mobile_app.
Simple messages without additional action data can be sent using notify.send_message where more advanced config (including stuff like priority, but also notification commands) can be sent using mobile_app.send_message. Both actions can target the mobile app notify entities.

[laupalombi]

@AuraHerreroRuiz hey, I really like your way of thinking around this topic. I also agree that a breaking change migration would make sense if there is an alternative that allows notifications simpler - we may be able to handle that.

I'm leaving leading this topic in the hands of @bgoncal and @TimoPtr since they mantain the iOS and Android project respectfully, and graciously bow out (but keep reading in background).