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 <marhje52@gmail.com> * Apply suggestions from code review Co-authored-by: Martin Hjelmare <marhje52@gmail.com> --------- Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
2025-04-19 10:57:14 +00:00 · 2024-04-13 01:03:14 +02:00 · 2024-04-13 01:03:14 +02:00 · 5347a1b7e0
commit 5347a1b7e0
parent 7d76bd8740
2 changed files with 72 additions and 0 deletions
--- a/blog/2024-04-10-new-notify-entity-platform.md
+++ 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.
--- a/docs/core/entity/notify.md
+++ 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."""
+```