Add new notify entity component

[jbouwh]

Context

More than 67 integrations (and custom integrations) implement the notify service platform. This platform was already marked as legacy, but no usable alternative is available yet. The platform can be set up via YAML or discovery by implementing get_service or async_get_service. An integration could use the shared notify.notify service are create custom service using targets. The user can then call the service by it's custom service name and this will call the send_message or async_send_message method of the legacy notify service.
Some dis-advantages are:

• The notify platform cannot be set up easily from a config entry. So most platforms set up the service from configuration.yaml.
• The custom services lack translations as they are generated dynamically.

Proposal

Implement an entity component platform for the notify integration.
As long as get_service or async_get_service is implemented, the legacy notify service will be set up.
New integrations should implement async_setup_entry. The platform will be able to add a new notify entity.
This entity will update it's state with the timestamp of the latest call.
The entity platform should implement either send_message or async_send_message.
It can be called with the notify.send_message service. The service attributes for title, recipients and data are optional but are to implemented in a later phase.
Intial the notify integration will not have supported features yet.

Aim is that integrations can add as many entities as needed (e.g. one per target). Users can target the entities through the new entity service. If integrations support a list of targets through a single entity service, then the entity should allow these targets to be passed as recipients to the service notify.send_message. This feature is not implemented in the initial version though. It will adopt the future model for contacts and groups as suggested here: #1041 (comment)

The initial implementation will be basic and only have one required parameter for messsage and the optional parameter title:

def send_message(self, message: str, title: str | None = None) -> None:
    """Send a message."""
    ...

async def async_send_message(self, message: str, title: str | None = None) -> None:
    """Send a message."""
    ....

Later we can add functionality for supplying recipients or additional data.

Device classes

Based on the inventory the intitial proposed device classes are:

    NotifyDeviceClass.DIRECT_MESSAGE = "direct_message"
    NotifyDeviceClass.DISPLAY = "display"
    NotifyDeviceClass.EMAIL = "email"
    NotifyDeviceClass.SMS = "sms"

Device class support will be left out of the MVP, to be implemented later.

Consequences

The use of the legacy service notify services should be deprecated in phases and integrations should implement the new notify entity platform. This is breaking because the custom notify services will no longer be available. Users should update their automation's to use the new service instead.

Prove of Concept

Prove of Concept (including demo in with the kitchen_sink integration): home-assistant/core#110950

Phased approach

In the fist phase of this proposal we'll implement a basic entity without features. We only apply it for basic notify integrations with predefined targets/recipients and without data. Setting a titile will be optional.

[MartinHjelmare]

It would be preferable to represent each notify target with an entity. The problem with that is that we don't know all targets before hand in some integrations.

I think a suggestion should solve this problem to be accepted.

[gjohansson-ST]

I took a brief look at the POC PR (to understand this better) and I think it looks good.
Maybe expand the device class from the beginning with the more generic types (e-mail, sms etc.) so we can have a nice frontend directly but I guess that's a bit more optional at this point.

[jbouwh]

I suggest the following device classes:

class NotifyDeviceClass(StrEnum):
    """Device class for notify entities."""

    DIRECT_MESSAGE = "direct_message"
    DISPLAY = "display"
    EMAIL = "email"
    SMS = "sms

[balloob]

Representing each target as an entity has two problems:

• If you integrate a mobile phone, would you create targets for the whole phone book?
• What if a user wants to add targets themselves?

I think we would benefit from getting an overview of what types of notification platforms there are, and try to create an optimal flow for each.

I've been playing with a design for the conversation integration which has a similar problem. My idea for it is that the integration can decide on some default entities, but users would be allowed to create entities that are stored in storage. Those entities would be created with configuration form provided by the integration.

So for example, for integrating a phone, you could create an entity that allows you to select a couple of targets from the phone book. The mobile app integration would just create the entities to target the mobile apps and user doesn't need to configure them.

[jbouwh]

Unlike the legacy notification service, the notifiy entity send_message method allows passing recipients. I have been thinking if we should have methods to allow adding or removing recipients, but decided to keep it simple. So for email or direct_message entities a user can pass multiple recipients. I think this way we solve the use case where the user needs to specify the targets, e.g. the recipients for an email or SMS.

[jbouwh]

May be an idea for the future, may be we could have a Contact Registry. With contact (and group) entities. I know some integrations that support contact (e.g. fritz). The caldav integration could allow importing your current contacts.
With that we could send messages by passing the contact or group entity id to the notification service.
We could also have helpers to allow the manual configuration of contacts. The current group integration can be used to group contact entities.

[balloob]

I discussed this proposal today with Martin, Robert and Eric. We agree and we want to move forward. However, we want to move with a small step first to get a feeling for how the architecture will work.

So I think the first step should be to add service entities only for cases where the recipient is fixed. For example, this would allow the mobile app integration to provide a notify entity.

I would not include supported feature support yet and just focus on message for the MVP.

I am writing up a proposal for config subentries (coming soon!), which can function as a contact registry as you described above for integrations like telegram.

[balloob]

Ah ok. I guess code owners of those integrations should update in the future when they move to a config flow.

[andrew-codechimp]

Just putting my hand up to say I've become a new code owner of the Mastodon integration and have migrated it to config flow recently, now has 86 users reported so less stale.
The notify service implementation has some niche uses of data elements so when you are looking to enhance Notify entity to cater for this I'm happy to spend some time seeing how we could implement this.

[MartinHjelmare]

The data parameter rework is up for grabs unless @jbouwh is working in the background on that.

Here's the idea for that:
#1041 (reply in thread)

[jbouwh]

The recipient parameter idea was to use sub entries. For the data parameter nothing is worked on, so any idea to do this more structured, i.e. using a dataclass or something like that would be welcome. May be we can start small and expand it when new integrations are to be migrated.

[andrew-codechimp]

I'll have a play around creating at least a basic notify entity and see what fits, certainly target/recipients I have a use for with Public/Private type scopes so separate entities may work for those.
I think I'm at the stage to be more of a follower/trial implementer than a solution provider for this but I'll give it some thought.

[jbouwh]

The following device classes are part of the proposal:

    NotifyDeviceClass.DIRECT_MESSAGE = "direct_message"
    NotifyDeviceClass.DISPLAY = "display"
    NotifyDeviceClass.EMAIL = "email"
    NotifyDeviceClass.SMS = "sms"

This will not be part of the MVP, so there is some time to discuss.

[jbouwh]

I'd like to extend the proposal with a title argument, this allows another 3 integrations to be converted.

• cisco_webex_teams (skipped: backend library not compatible with python 3.12)
• file Migrate file integration to config entry core#116861 and Migrate File notify entity platform core#117215
• sendgrid (skipped: only 2 active reported installs)
• syslog (skipped: only 5 active reported installs)
• tibber Migrate Tibber notify service core#116893

The send_message API gets a new optional title argument.

    def send_message(self, message: str, title: str | None = None) -> None:
        """Send a message."""
        ...

    async def async_send_message(self, message: str, title: str | None = None) -> None:
        """Send a message."""
        ...

Integration supporting the title arg should add the NotifyEntityFeature.TITLE feature.

Draft PR to implement the proposal: home-assistant/core#116426

[MartinHjelmare]

The title parameter and supported feature looks good. 👍

[robinsmidsrod]

I'm not sure I'm rocking the boat here, but the model name "notify" seems off to me. All other entity domains are nouns (sensor, button, switch, etc), but the word "notify" is a verb, not a noun. A sentence where you say "all my notifys are misbehaving because..." seems very weird to me, even as a non-native speaker. Shouldn't it be a noun, such as "notification", "notifier" or similar?

[parautenbach]

@robinsmidsrod I agree with your thinking and with that in mind, it should probably have been called notification in restrospect. On the other hand, notification.notify reads a bit odd too (because you don't notify the notification) and doesn't feel the same as switch.turn_on. It's the kind of legacy that will probably remain though, as changing it may have too many consequences. That said, since it's being migrated, this might be the most opportune moment to do something like that.

[robinsmidsrod]

@parautenbach Glad to hear I'm not alone in thinking there was something "off" here. As they say, there are only two hard things in IT, "naming things and off-by-one errors". ;)

What I find interesting here is, what does the entity represent?

• The action of sending the message (notify/send)
• The message itself (notification)
• The thing/service sending the message (notifier)
• Possibly even the recipient of the message (recipient/destination?)

From my reading of this thread the entity seems to represent the thing/service that is responsible for sending the message, i.e. notifier.

But as @jbouwh mentioned, this is already an existing platform, changing it at this point is probably too much work for too little benefit.

[parautenbach]

As you say there: It's hard and some of those questions crossed my mind too. I can live with it. I you cannot fix/change it, at least document it, and at least we know this is very well documented. :-)

[jgeldart]

Are there plans for richer messages? My use case is a form of multimodal interface: having a card (of some description) shown on some 'surface' (such as a phone/tablet app, TV, computer) which can be interacted with. For example, if I'm having a conversation with a smart assistant about the lights then it could send a card for the lights we're talking about to the nearest surface to me. These cards could also include richer information, visualisations, etc. for cases where just voice isn't sufficient (if 2023 was the Year of the Voice, I am thinking of 2024/25 as my personal Year of Multimodal).

In my head, I see these rich messages as having text, speech (SSML), and interactable cards (perhaps described using an existing extensible, declarative spec that can be rendered for different surfaces and could be dynamically generated by an LLM, like Microsoft's Adaptive Cards).

[jbouwh]

@jgeldart At first the aim is to replace the legacy service implementation. At least I expect there will be recipient support. The use of the data attribute , as we have it now, might change. Proposals for extensions of the notify entity will follow.
As message a user could send any text format through the notify.send_message service. I do not see that could not be HTML or some other format, as long, as long as it is used for sending notification messages.

[nielsfaber]

@jbouwh Are any updates planned for this?
Currently there seems to be a bit of a mixup between the legacy format and integrations using the new notify.send_message method.
When will the other notify platforms (such as mobile_app and persistent_notification) be converted?
For sake of consistency I would suggest to not leave the migration period open for too long.

[jbouwh]

You are right. The steps to take here are a replacement for the recipient, and for additional data. @balloob has left use some ideas to use subentries. There is a draft PR that has come close to be merged.
So if we are talking about data or a recipient this could as well be a subentry or a recipient.
But for a recipient may be we should not have subentries in all cases.
We could think of a dataclass that can contain email, a (mobile) number or identifier to pass a recipient, may be use some feature flags.
On the other hand a person registry might be a good idea, as there are some integration like fritz that could link these from the built-in contacts.
For this to happen we need a good proposal first, so feel free to step in.

[jbouwh]

I have looked into the usage and patterns of the custom data parameter, and it seems that it is used for anything. There is no structure or pattern in it.
To allow the migration of some legacy services that no use fix targets / recipients, and make use of custom data I suggest we pass data as dict[str, Any]. This way it will be easier for user to update there automation's and scripts when integrations are updated to use the new notify entities.

The new signature for the send_message API method would become:

    def send_message(self, message: str, title: str | None = None, data: dict[str, Any] | None = None) -> None:
        """Send a message."""
        ...

    async def async_send_message(self, message: str, title: str | None = None, data: dict[str, Any] | None = None) -> None:
        """Send a message."""
        ...

Integration we can potentially migrate to use the new notification entities are listed below:

integration	name	config_flow	title	data	target	Fixed recipient	class	remark
bmw_connected_drive	BMW Connected Drive	True	False	True	False	True	api message
homematic	Homematic	False	False	True	False	True	api device command	May be this should a custom service, does not use message which is required
html5	HTML5 Push Notifications	False	True	True	False	True	direct message	Uses multiple targets  predefined from config
ios	Home Assistant iOS	True	True	True	True	True	direct message	Target is a predefined push id, could be separat entries
joaoapps_join	Joaoapps Join	False	True	True	False	True	direct message
keba	Keba Charging Station	False	False	True	False	True	screen device	Text on LCD screen, could have been a text entity as well
kodi	Kodi	True	True	True	False	True	direct message	Text on screen
lametric	LaMetric	True	False	True	False	True	screen device
lannouncer	LANnouncer	False	True	True	False	True	text to speech	Sound or TTS to Android App
llamalab_automate	LlamaLab Automate	False	True	True	False	True	direct message	Predefined recipient, message to Android App
mailgun	Mailgun	True	True	True	False	True	email	Predefined recipient
mobile_app	Mobile App	True	True	True	True	True	direct message	Entity per push registration could be used
msteams	Microsoft Teams	False	True	True	False	True	direct message	Entity per group target (config)
nfandroidtv	Notifications for Android TV / Fire TV	True	True	True	False	True	direct message
notify_events	Notify.Events	False	False	True	False	True	direct message
prowl	Prowl	False	True	True	False	True	direct message
rest	RESTful	False	True	True	True	True	api message	Target is a pre-defined param (one allowed per call)
rocketchat	Rocket.Chat	False	False	True	False	True	direct message
signal_messenger	Signal Messenger	False	False	True	False	True	direct message
simplepush	Simplepush	True	True	True	False	True	direct message
synology_chat	Synology Chat	False	False	True	False	True	direct message
system_bridge	System Bridge	True	True	True	False	True	screen device
webostv	LG webOS Smart TV	True	False	True	False	True	screen device	Data is used to set an icon
xmpp	Jabber (XMPP)	False	True	True	False	True	direct message	Recipients in config

[MartinHjelmare]

I don't agree. The idea was not to be able to migrate the data parameter as is but to find common items that this parameter is used for.

There are eg many integrations that use it for images and urls. We could then add parameters for image and url and allow those integrations to leverage them for that part of their provider service API. For provider parameters where there are no common parameter yet in Home Assistant for the send message action service, integrations can either keep using the legacy notify action service and/or register new custom action services.

[jbouwh]

So you mean the new parameters should replace the use of non typed dict values?

[MartinHjelmare]

I don't think we should add any parameters that allows non typed non validated values to the new action service. This will probably mean that all existing parameters of the old action service won't be supported by the new action service and that's ok. Integrations can register custom entity services with whatever parameters they need.