From 0d3fbaae6e7cfda0346f59435dee4fbb34de10fd Mon Sep 17 00:00:00 2001
From: RoboMagus <68224306+RoboMagus@users.noreply.github.com>
Date: Tue, 27 Jun 2023 12:21:19 +0200
Subject: [PATCH] Add persistent_notification automation trigger to docs
 (#27860)

Co-authored-by: J. Nick Koston <nick@koston.org>
Co-authored-by: Franck Nijhof <frenck@frenck.nl>
---
 source/_docs/automation/templating.markdown   | 14 +++++++++++
 source/_docs/automation/trigger.markdown      | 17 +++++++++++++
 .../persistent_notification.markdown          | 25 +++++++++++++++++++
 3 files changed, 56 insertions(+)

diff --git a/source/_docs/automation/templating.markdown b/source/_docs/automation/templating.markdown
index 2c0786cee58..b3ed854a918 100644
--- a/source/_docs/automation/templating.markdown
+++ b/source/_docs/automation/templating.markdown
@@ -144,6 +144,20 @@ These are the properties available for a [Time Pattern trigger](/docs/automation
 | `trigger.platform` | Hardcoded: `time_pattern`
 | `trigger.now` | DateTime object that triggered the time_pattern trigger.
 
+### Persistent Notification
+
+These properties are available for a [Persistent Notification trigger](/docs/automation/trigger/#persistent-notification-trigger).
+
+| Template variable | Data |
+| ---- | ---- |
+| `trigger.platform` | Hardcoded: `persistent_notification`
+| `trigger.update_type` | Type of persistent notification update `added`, `removed`, `current`, or `updated`.
+| `trigger.notification` | Notification object that triggered the persistent notification trigger.
+| `trigger.notification.notification_id` | The notification ID
+| `trigger.notification.title` | Title of the notification
+| `trigger.notification.message` | Message of the notification
+| `trigger.notification.created_at` | DateTime object indicating when the notification was created.
+
 ### Webhook
 
 These are the properties available for a [Webhook trigger](/docs/automation/trigger/#webhook-trigger).
diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown
index 05c1b1d7f1f..880ee70cc73 100644
--- a/source/_docs/automation/trigger.markdown
+++ b/source/_docs/automation/trigger.markdown
@@ -19,6 +19,7 @@ An automation can be triggered by an event, a certain entity state, at a given t
 - [Template trigger](#template-trigger)
 - [Time trigger](#time-trigger)
 - [Time pattern trigger](#time-pattern-trigger)
+- [Persistent notification trigger](#persistent-notification-trigger)
 - [Webhook trigger](#webhook-trigger)
 - [Zone trigger](#zone-trigger)
 - [Geolocation trigger](#geolocation-trigger)
@@ -778,6 +779,22 @@ Do not prefix numbers with a zero - using `'01'` instead of `'1'` for example wi
 
 </div>
 
+## Persistent notification trigger
+
+Persistent notification triggers are fired when a `persistent_notification` is `added` or `removed` that matches the configuration options.
+
+```yaml
+automation:
+  trigger:
+    - platform: persistent_notification
+      update_type:
+        - added
+        - removed
+      notification_id: invalid_config
+```
+
+See the [Persistent Notification](/integrations/persistent_notification/) integration for more details on event triggers and the additional event data available for use by an automation.
+
 ## Webhook trigger
 
 Webhook trigger fires when a web request is made to the webhook endpoint: `/api/webhook/<webhook_id>`. The webhook endpoint is created automatically when you set it as the `webhook_id` in an automation trigger.
diff --git a/source/_integrations/persistent_notification.markdown b/source/_integrations/persistent_notification.markdown
index 0aabbbdd8df..a116cf3ff96 100644
--- a/source/_integrations/persistent_notification.markdown
+++ b/source/_integrations/persistent_notification.markdown
@@ -18,6 +18,31 @@ The `persistent_notification` integration can be used to show a notification on
   <img src='/images/screenshots/persistent-notification.png' />
 </p>
 
+## Automation
+
+Persistent notification [triggers](/docs/automation/trigger) enable automations to be triggered when persistent notifications are updated. Triggers can be limited to a specific notification by providing an ID for `notification_id`, or when this value is omitted the automation will trigger for any notification ID. If no `update_type` is provided, the automation will trigger for the following update types: `added`, `removed`, `updated`, or `current`. By providing one or more of these values to the `update_type` option, the automation triggers only on these `update_type` events.
+
+Review the [Automating Home Assistant](/getting-started/automation/) getting started guide on automations or the [Automation](/docs/automation/) documentation for full details.
+
+{% my automations badge %}
+
+An example of a persistent notification trigger in YAML:
+
+```yaml
+automation:
+  - trigger:
+      - platform: persistent_notification
+        # Optional. Possible values: added, removed, updated, current
+        update_type:
+          - added
+          - removed
+        # Optional.
+        notification_id: invalid_config
+```
+
+See [Automation Trigger Variables: Persistent Notification](/docs/automation/templating/#persistent-notification) 
+for additional trigger data available for conditions or actions.
+
 ### Service
 
 The service `persistent_notification.create` takes in `message`, `title`, and `notification_id`.