From 5347a1b7e09ba7af8f63138b9f085b00a06d7c99 Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Sat, 13 Apr 2024 01:03:14 +0200 Subject: [PATCH] Add notify entity platform (#2135) * Add notify entity platform * Add blog post * tweak * more tweaks * Also document non async method * Apply suggestions from code review Co-authored-by: Martin Hjelmare * Apply suggestions from code review Co-authored-by: Martin Hjelmare --------- Co-authored-by: Martin Hjelmare --- blog/2024-04-10-new-notify-entity-platform.md | 32 +++++++++++++++ docs/core/entity/notify.md | 40 +++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 blog/2024-04-10-new-notify-entity-platform.md create mode 100644 docs/core/entity/notify.md diff --git a/blog/2024-04-10-new-notify-entity-platform.md b/blog/2024-04-10-new-notify-entity-platform.md new file mode 100644 index 00000000..b42a564d --- /dev/null +++ b/blog/2024-04-10-new-notify-entity-platform.md @@ -0,0 +1,32 @@ +--- +author: Jan Bouwhuis +authorURL: https://github.com/jbouwh +authorImageURL: https://avatars.githubusercontent.com/u/7188918?s=96&v=4 +title: New notify entity platform +--- + +### New notify entity platform + +The notify platform is now available as an [entity platform](https://developers.home-assistant.io/docs/core/entity/notify/). The MVP for the new `notify` platform [implements](https://github.com/home-assistant/core/pull/110950) the method and service `send_message`. It accepts `message` as a required attribute. +Unlike the legacy `notify.notify` service we have no targets as argument, as it is an entity we can target multiple `notify` entities when calling `send_message`. + +The [architecture discussion](https://github.com/home-assistant/architecture/discussions/1041) is ongoing, and is about the device classes to implement and the implementation of recipient support in the form of [contacts via a contact registry](https://github.com/home-assistant/architecture/discussions/1041#discussioncomment-8947842). + +Existing integrations that implement the legacy `notify` services will be migrated in phases. The first step is to migrate the integrations than only use `message` as a parameter to notify. + +The integrations identified for migration are: + +- circuit +- clickatell +- clicksend +- command_line +- demo +- ecobee +- flock +- free_mobile +- knx +- mastodon + +As soon as we have `title` and/or `recipient` support we can migrate more integrations to use the new platform. + +When integrations are migrated, users will need to use the new `notify.send_message` service, so the migration changes will cause automations to break after the deprecation period is over. diff --git a/docs/core/entity/notify.md b/docs/core/entity/notify.md new file mode 100644 index 00000000..701e97cc --- /dev/null +++ b/docs/core/entity/notify.md @@ -0,0 +1,40 @@ +--- +title: Notify Entity +sidebar_label: Notify +--- + +A notify entity is an entity that can send a message towards a device or service but remains stateless from the Home Assistant perspective. + +A notify entity is derived from the [`homeassistant.components.notify.NotifyEntity`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/notify/__init__.py), +and can be helpful to send notification messages as (but not limited to): + +- an SMS +- an email +- a direct message or chat +- a screen message on a device's LCD display + +Unlike a `text` entity the `notify` entity has no state that can be set. Instead it represents the date and time of the last message sent. + +If you want to represent something that has a text value that can be changed (and thus has an actual state), you should use a `text` entity instead. + +## Properties + +As this integration is stateless, it doesn't provide any specific properties for itself. +Other properties that are common to all entities such as `icon` and `name` etc are still applicable. + +## Methods + +### Send message + +The send message method is used to send a message to a device or service. + +```python +class MyNotifier(NotifyEntity): + # Implement one of these methods. + + def send_message(self, message: str) -> None: + """Send a message.""" + + async def async_send_message(self, message: str) -> None: + """Send a message.""" +```