From f8a684b79c8eb0fd3d305dc1ad10d88b9a342f4e Mon Sep 17 00:00:00 2001
From: Michael Hansen <hansen.mike@gmail.com>
Date: Thu, 27 Jul 2023 13:31:02 -0500
Subject: [PATCH] Document sentence trigger wildcards (#28332)

---
 source/_docs/automation/templating.markdown | 11 +++++++++++
 source/_docs/automation/trigger.markdown    | 17 +++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/source/_docs/automation/templating.markdown b/source/_docs/automation/templating.markdown
index b3ed854a918..dc2c2d77723 100644
--- a/source/_docs/automation/templating.markdown
+++ b/source/_docs/automation/templating.markdown
@@ -92,6 +92,17 @@ These are the properties available for a [Numeric State trigger](/docs/automatio
 | `trigger.to_state` | The new [state object] that triggered trigger.
 | `trigger.for` | Timedelta object how long state has met above/below criteria, if any.
 
+### Sentence
+
+These are the properties available for a [Sentence trigger](/docs/automation/trigger/#sentence-trigger).
+
+| Template variable | Data |
+| ---- | ---- |
+| `trigger.platform` | Hardcoded: `conversation`
+| `trigger.sentence` | Text of the sentence that was matched
+| `trigger.slots`    | Object with matched slot values
+| `trigger.details` | Object with matched slot details by name, such as [wildcards](/docs/automation/trigger/#sentence-wildcards). Each detail contains: <ul><li>`name` - name of the slot</li><li>`text` - matched text</li><li>`value` - output value (see [lists](https://developers.home-assistant.io/docs/voice/intent-recognition/template-sentence-syntax/#lists))</li></ul>
+
 ### State
 
 These are the properties available for a [State trigger](/docs/automation/trigger/#state-trigger).
diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown
index fa8cdc5709c..049bc8ca85e 100644
--- a/source/_docs/automation/trigger.markdown
+++ b/source/_docs/automation/trigger.markdown
@@ -939,6 +939,23 @@ The sentences matched by this trigger will be:
 
 Punctuation and casing are ignored, so "It's PARTY TIME!!!" will also match.
 
+### Sentence Wildcards
+
+Adding one or more `{lists}` to your trigger sentences will capture any text at that point in the sentence. A `slots` object will be [available in the trigger data](/docs/automation/templating#sentence).
+This allows you to match sentences with variable parts, such as album/artist names or a description of a picture.
+
+For example, the sentence `play {album} by {artist}` will match "play the white album by the beatles" and have the following variables available in the action templates:
+
+{% raw %}
+
+- `{{ trigger.slots.album }}` - "the white album"
+- `{{ trigger.slots.artist }}` - "the beatles"
+
+{% endraw %}
+
+Wildcards will match as much text as possible, which may lead to surprises: "play day by day by taken by trees" will match `album` as "day" and `artist` as "day by taken by trees".
+Including extra words in your template can help: `play {album} by artist {artist}` can now correctly match "play day by day by artist taken by trees".
+
 ## Multiple triggers
 
 It is possible to specify multiple triggers for the same rule. To do so just prefix the first line of each trigger with a dash (-) and indent the next lines accordingly. Whenever one of the triggers fires, processing of your automation rule begins.