Skip to content

Update templating.markdown #38961

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: current
Choose a base branch
from
+75 −34
Open

Update templating.markdown #38961

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
161f1c1
Update templating.markdown
MarkusBiggus May 9, 2025
aa96186
Update templating.markdown
MarkusBiggus May 10, 2025
e44b62e
Update templating.markdown
MarkusBiggus May 10, 2025
45543f1
Update source/_docs/automation/templating.markdown
MarkusBiggus May 10, 2025
5bd53c2
Update source/_docs/automation/templating.markdown
MarkusBiggus May 10, 2025
56ffeae
Update source/_docs/automation/templating.markdown
MarkusBiggus May 10, 2025
5fe39bb
Update templating.markdown
MarkusBiggus May 10, 2025
db36f23
Merge branch 'current' into patch-4
MarkusBiggus May 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 75 additions & 34 deletions source/_docs/automation/templating.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,37 @@
---
title: "Automation trigger variables"
description: "List all available variables made available by triggers."
title: "Automation Templates"
description: "List all trigger variables available to templates."
---

Automations support [templating](/docs/configuration/templating/) in the same way as scripts do. In addition to the [Home Assistant template extensions](/docs/configuration/templating/#home-assistant-template-extensions) available to scripts, the `trigger` and `this` template variables are available.
Automations support the advanced features of [templating](/docs/configuration/templating/) in the same way as scripts do. In addition to the [Home Assistant template extensions](/docs/configuration/templating/#home-assistant-template-extensions) available to scripts, the `trigger` and `this` template variables are available for automations.

The template variable `this` is also available when evaluating any `trigger_variables` declared in the configuration.
Example of variables used in templates:

## Available `this` data
```jinja
{{ this.name }} is the name of the automation executing from this trigger
{{ trigger.platform }} is the type of trigger object, like `calendar`
```

The variable `this` is the [state object](/docs/configuration/state_object) of the automation at the moment of triggering the actions. State objects also contain context data which can be used to identify the user that caused a {% term script %} or {% term automation %} to execute. Note that `this` will not change while executing the {% term actions %}.
## Available state data

The template variable `this` is an object that contains the [state](/docs/configuration/state_object) of the automation at the moment of triggering the actions and can be used to evaluate [`trigger_variables`](/docs/automation/trigger/#trigger-variables) declared in the configuration of the active {% term trigger %}.
State objects also contain context data which can be used to identify the user that caused a {% term script %} or {% term automation %} to execute. Note that `this` will not change while executing the {% term actions %}.

## Available trigger data

The variable `trigger` is an object that contains details about which {% term trigger %} triggered the automation.
The template variable `trigger` is an object that contains details about which {% term platform %} triggered the automation. The `platform` property contains the name of the {% term platform %} whose event triggered the automation.

Templates can use the data to modify the actions performed by the automation or displayed in a message. For example, you could create an automation that multiple sensors can trigger and then use the sensor's location to specify a light to activate; or you could send a notification containing the friendly name of the sensor that triggered it.

Each [trigger platform](/docs/automation/trigger/#event-trigger) can include additional data specific to that platform.
Each [trigger](/docs/automation/trigger/#event-trigger) platform includes additional data specific to that {% term platform %}.

### All

Triggers from all platforms will include the following data.
Triggers from all platforms will include the following properties.

| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Trigger object type.
| `trigger.alias` | Alias of the trigger.
| `trigger.id` | The [`id` of the trigger](/docs/automation/trigger/#trigger-id).
| `trigger.idx` | Index of the trigger. (The first trigger idx is `0`.)
Expand All @@ -33,18 +40,18 @@ Triggers from all platforms will include the following data.

These are the properties available for a [Calendar trigger](/docs/automation/trigger/#calendar-trigger).

| Template variable | Data |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `trigger.platform` | Hardcoded: `calendar` |
| `trigger.event` | The trigger event type, either `start` or `end` |
| `trigger.calendar_event` | The calendar event object matched. |
| `trigger.calendar_event.summary` | The title or summary of the calendar event. |
| `trigger.calendar_event.start` | String representation of the start date or date time of the calendar event e.g. `2022-04-10`, or `2022-04-10 11:30:00-07:00` |
| `trigger.calendar_event.end` | String representation of the end time of date time the calendar event in UTC e.g. `2022-04-11`, or `2022-04-10 11:45:00-07:00` |
| `trigger.calendar_event.all_day` | Indicates the event spans the entire day. |
| `trigger.calendar_event.description` | A detailed description of the calendar event, if available. |
| `trigger.calendar_event.location` | Location information for the calendar event, if available. |
| `trigger.offset` | Timedelta object with offset to the event, if any |
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `calendar`
| `trigger.event` | The trigger event type, either `start` or `end`.
| `trigger.calendar_event` | The calendar event object matched.
| `trigger.calendar_event.summary` | The title or summary of the calendar event.
| `trigger.calendar_event.start` | String representation of the start date or date time of the calendar event e.g. `2022-04-10`, or `2022-04-10 11:30:00-07:00`
| `trigger.calendar_event.end` | String representation of the end time of date time the calendar event in UTC e.g. `2022-04-11`, or `2022-04-10 11:45:00-07:00`
| `trigger.calendar_event.all_day` | Indicates the event spans the entire day.
| `trigger.calendar_event.description` | A detailed description of the calendar event, if available.
| `trigger.calendar_event.location` | Location information for the calendar event, if available.
| `trigger.offset` | Timedelta object with offset to the event, if any.

### Device

Expand All @@ -54,26 +61,50 @@ Inherites template variables from [event](#event) or [state](#state) template ba

| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `device`.
| `trigger.platform` | Hardcoded: `device`

### Event

These are the properties available for a [Event trigger](/docs/automation/trigger/#event-trigger).
An [Event](/docs/configuration/events/) trigger is fired each time an {% term entity %} state changes or an event matching the configured event_type occurs.

These are the properties available for an [Event trigger](/docs/automation/trigger/#event-trigger).

| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `event`.
| `trigger.event` | Event object that matched.
| `trigger.platform` | Hardcoded: `event`
| `trigger.event` | Event object that matched.
| `trigger.event.event_type` | Event type.
| `trigger.event.data` | Optional event data.
| `trigger.event.data` | Optional event data.
Comment on lines +74 to +77
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix Event Table Formatting
Add trailing pipes to each row in the Event trigger table to satisfy markdownlint MD055.

- | `trigger.platform`       | Hardcoded: `event`
+ | `trigger.platform`       | Hardcoded: `event` |
- | `trigger.event`          | Event object that matched.
+ | `trigger.event`          | Event object that matched. |
- | `trigger.event.data`     | Optional event data.
+ | `trigger.event.data`     | Optional event data. |

Committable suggestion skipped: line range outside the PR's diff.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

74-74: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe

(MD055, table-pipe-style)

75-75: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe

(MD055, table-pipe-style)

76-76: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe

(MD055, table-pipe-style)

77-77: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe

(MD055, table-pipe-style)


### Geolocation

These are the properties available for a [Geolocation trigger](/docs/automation/trigger/#geolocation-trigger).

| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `geo_location`
| `trigger.event` | The trigger event type, either `enter` or `leave`.
| `trigger.source` | The Geolocation platform creating the trigger event.
| `trigger.zone` | State object of the zone.

### Home Assistant

The Home Assistant trigger is recommended for automations instead of [homeassistant_start or homeassistant_stop events](/docs/configuration/events/#homeassistant_start-homeassistant_started).

These are the properties available for a [Home Assistant trigger](/docs/automation/trigger/#home-assistant-trigger).

| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `homeassistant`
| `trigger.event` | The trigger event type, either `start` or `shutdown`.

### MQTT

These are the properties available for a [MQTT trigger](/docs/automation/trigger/#mqtt-trigger).

| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `mqtt`.
| `trigger.platform` | Hardcoded: `mqtt`
| `trigger.topic` | Topic that received payload.
| `trigger.payload` | Payload.
| `trigger.payload_json` | Dictionary of the JSON parsed payload.
Expand All @@ -100,9 +131,9 @@ These are the properties available for a [Sentence trigger](/docs/automation/tri
| 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>
| `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](/docs/voice/intent-recognition/template-sentence-syntax/#lists))</li></ul>.
| `trigger.device_id` | The device ID that captured the command, if any.

### State
Expand All @@ -127,6 +158,16 @@ These are the properties available for a [Sun trigger](/docs/automation/trigger/
| `trigger.event` | The event that just happened: `sunset` or `sunrise`.
| `trigger.offset` | Timedelta object with offset to the event, if any.

### Tag

These are the properties available for a [Tag trigger](/docs/automation/trigger/#tag-trigger).

| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `tag`
| `trigger.tag_id` | The tag ID captured.
| `trigger.device_id` | Optional device ID that captured the tag.

### Template

These are the properties available for a [Template trigger](/docs/automation/trigger/#template-trigger).
Expand Down Expand Up @@ -166,9 +207,9 @@ These properties are available for a [persistent notification trigger](/docs/aut
| `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.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
Expand All @@ -193,7 +234,7 @@ These are the properties available for a [Zone trigger](/docs/automation/trigger
| `trigger.entity_id` | Entity ID that we are observing.
| `trigger.from_state` | Previous [state object] of the entity.
| `trigger.to_state` | New [state object] of the entity.
| `trigger.zone` | State object of zone
| `trigger.zone` | State object of the zone.
| `trigger.event` | Event that trigger observed: `enter` or `leave`.

## Examples
Expand Down