When an automation or script runs, it goes through a list of steps. Each step is an action or a building block:

• An action makes something happen, for example, turning on a light or sending a notification. Home Assistant performs the action on the targets you choose. For a list of all actions, refer to the actions reference.
• A building block controls whether, when, and in which order the other steps run. It can check a condition, wait, repeat steps, choose between steps, or perform steps at the same time.

Automations and scripts use the same actions and building blocks.

How automations and scripts run their steps

When an automation starts, it first checks its conditions under And if. If they are met, it goes through the steps under Then do, from top to bottom. A script has no conditions section, so it goes through its steps under Sequence right away.

The difference is when they run: an automation runs by itself when one of its triggers reacts, and a script runs when you start it, for example, from a dashboard, from an automation, or with Assist. For more about the difference, refer to Concepts and terminology.

To add a step in the editor, select Add action. To add a building block, select Blocks in that dialog. In YAML, you write actions and building blocks in the same list. For details, refer to Writing steps in YAML.

For how to create scripts, pass them variables, and wait for them to finish, refer to the Scripts integration.

Performing an action

To make something happen, such as turning on a light, add an action. Each action has its own page with its options, listed in the actions reference. For the options that most actions share, such as targets and data, refer to Performing actions.

Adding an action in the editor

To add an action in the automation or script editor, follow the steps in Adding an action in the editor.

Performing an action in YAML

In YAML, use action with the name of the action, and optionally target and data:

alias: "Bedroom lights on"
action: light.turn_on
target:
  entity_id: light.bedroom
data:
  brightness: 100

In older YAML, you may find a shortcut to activate a sceneScenes capture the states you want certain entities to be. For example, a scene can specify that light A should be turned on and light B should be bright red. [Learn more]. It does the same as the Activate scene action. When you open the step in the editor, the editor changes it to action: scene.turn_on.

scene: scene.morning_living_room

Fire manual event

The Fire manual event action fires an event. Other automations can react to it with a Manual event received trigger. Use it to let one automation or script tell another that something happened, and to pass data along.

Adding Fire manual event in the editor

1. Go to Settings > Automations & scenes and select an automation. To edit a script, go to the Scripts tab and select the script.
2. In the Then do section of an automation, or the Sequence section of a script, select Add action.
3. Search for and select Fire manual event.
4. In Event type, enter the name of the event, for example, event_light_state_changed.
5. Optional: In Event data, enter the data to send with the event, in YAML.
6. Select Save.

Options in the UI

Fire manual event in YAML

In YAML, use event with the event type, and optionally event_data. The event data accepts templates:

event: MY_EVENT
event_data:
  name: myEvent
  customData: "{{ myCustomVariable }}"

Options in YAML

Good to know about Fire manual event

• To add an entry to the Activity panel, use the Log activity action.

Examples of Fire manual event

Automation: Fire a custom event when a switch turns on

When the kitchen switch turns on, this automation fires the custom event event_light_state_changed, with the new state as event data. The actions could also be part of a script.

alias: "Fire event"
triggers:
  - trigger: state
    entity_id: switch.kitchen
    to: "on"
actions:
  - event: event_light_state_changed
    event_data:
      state: "on"

Automation: React to the custom event

This automation reacts to event_light_state_changed with a Manual event received trigger, and uses the state from the event data in a notification. For the data you can use, refer to available trigger data.

alias: "Capture event"
triggers:
  - trigger: event
    event_type: event_light_state_changed
actions:
  - action: notify.notify
    data:
      message: "The kitchen light is turned {{ trigger.event.data.state }}."

Set conversation response

The Set conversation response action sets what Assist says, or shows, when a voice command or sentence starts the automation. Use it with a sentence trigger to answer a custom command.

Adding Set conversation response in the editor

1. Go to Settings > Automations & scenes and open the automation that has the sentence trigger.
2. In the Then do section, select Add action.
3. Search for and select Set conversation response.
4. In Set conversation response, enter the response. You can use a template, for example, to include the state of an entity.
5. Select Save.

Options in the UI

Set conversation response in YAML

In YAML, use set_conversation_response with the response. The response can be a template:

- variables:
    my_var: "123"
- set_conversation_response: "{{ 'Testing ' ~ my_var }}"

This example responds with “Testing 123”.

To clear a response that an earlier step set, set it to empty:

set_conversation_response:

Options in YAML

Good to know about Set conversation response

• Assist uses the response when the automation finishes. If the automation sets the response more than once, the last one is used.
• If the automation didn’t start from a conversation, for example, from a time trigger, the response isn’t used.
• Set the response in the automation itself. If the automation runs a script, a response that the script sets doesn’t reach Assist. To use data from a script, let the script return a response with Stop, and use that data in the automation’s Set conversation response.

Examples of Set conversation response

Automation: Answer whether the garage door is open

When you ask Assist “Is the garage door open?”, this automation answers with the current state of the garage door, for example, “The garage door is closed.”

• Trigger: Sentence
  • Sentence: Is the garage door open
• Action: Set conversation response
  • Set conversation response: The garage door is {{ states('cover.garage_door') }}.

alias: "Answer whether the garage door is open"
triggers:
  - trigger: conversation
    command: "Is the garage door open"
actions:
  - set_conversation_response: >
      The garage door is {{ states('cover.garage_door') }}.

Choose

The Choose building block has several options, each with its own conditions and actions. For the steps, options, and examples, refer to Choose.

Condition

The Condition building block checks a condition in the middle of a sequence. For the steps, options, and examples, refer to Condition.

Define variables

The Define variables building block sets variables that templates in the next steps can use. For the steps, options, and examples, refer to Define variables.

If-then

The If-then building block runs actions only if its conditions are met. For the steps, options, and examples, refer to If-then.

Repeat for each

The Repeat for each building block runs a group of actions once for each item in a list. For the steps, options, and examples, refer to Repeat for each.

Repeat multiple times

The Repeat multiple times building block runs a group of actions a set number of times. For the steps, options, and examples, refer to Repeat multiple times.

Repeat until

The Repeat until building block runs a group of actions until its conditions are met. For the steps, options, and examples, refer to Repeat until.

Repeat while

The Repeat while building block runs a group of actions as long as its conditions are met. For the steps, options, and examples, refer to Repeat while.

Run in sequence

The Run in sequence building block groups actions that run one after the other. For the steps, options, and examples, refer to Run in sequence.

Run in parallel

The Run in parallel building block starts several actions at the same time, instead of one after the other. For the steps, options, and examples, refer to Run in parallel.

Stop

The Stop building block stops the automation or script. For the steps, options, and examples, refer to Stop.

Wait for time to pass (delay)

The Wait for time to pass (delay) building block pauses the automation or script for a set time. For the steps, options, and examples, refer to Wait for time to pass (delay).

Wait for a template

The Wait for a template building block pauses the automation or script until a template is true. For the steps, options, and examples, refer to Wait for a template.

Wait for a trigger

The Wait for a trigger building block pauses the automation or script until one of its triggers reacts to a change. For the steps, options, and examples, refer to Wait for a trigger.

Writing steps in YAML

In YAML, the steps are a list under actions: in an automation, or under sequence: in a script. If there is only one step, you can leave out the list.

Every step can have an alias. The alias is the name of the step that the editor and the trace show. In the editor, you set it with Rename.

In an automation, the steps go under actions::

actions:
  - alias: "Turn on ceiling light"
    action: light.turn_on
    target:
      entity_id: light.ceiling
  - alias: "Notify that ceiling light is turned on"
    action: notify.notify
    data:
      message: "Turned on the ceiling light!"

In a script, the same steps go under sequence::

sequence:
  - alias: "Turn on ceiling light"
    action: light.turn_on
    target:
      entity_id: light.ceiling
  - alias: "Notify that ceiling light is turned on"
    action: notify.notify
    data:
      message: "Turned on the ceiling light!"

In an automation, templates in the steps can use the trigger variable, which describes what started the automation. For details, refer to available trigger data.

Options for any step

These options work on every step, both actions and building blocks. The only exception is Continue on error, which conditions don’t have.

Continuing when a step fails

By default, an automation or script stops when a step fails. The run is marked as failed, and the error is logged. If a step can fail without affecting the rest, for example, a notification to an unreliable service, you can continue with the next step instead.

In the editor, in the Menu of the step, select Continue on error. For details, refer to Continuing after an action fails.

In YAML, add continue_on_error: true to the step:

- alias: "If this one fails..."
  continue_on_error: true
  action: notify.super_unreliable_service_provider
  data:
    message: "I'm going to error out..."

alias: "This one still runs"
action: persistent_notification.create
data:
title: "Hi there!"
message: "I'm fine…"

Continue on error doesn’t ignore errors in the configuration, such as a broken template. The error is still shown in the trace and in the logs.

An action whose target is unavailable or doesn’t exist doesn’t fail. Home Assistant skips that target and logs a warning, so the next step runs even without Continue on error. The action does fail if an entity that you selected directly doesn’t support it, or if the action should return response data and none of its targets match.

Turning off a step

To try an automation or script without one of its steps, turn the step off instead of deleting it. Home Assistant skips it until you turn it on again.

In the editor, in the Menu of the step, select Disable. For details, refer to Turning off a trigger, condition, or action.

In YAML, add enabled: false to the step:

actions:
  # This step is skipped.
  - enabled: false
    alias: "Notify that the ceiling light is being turned on"
    action: notify.notify
    data:
      message: "Turning on the ceiling light!"
This step runs.

alias: "Turn on the ceiling light"
action: light.turn_on
target:
entity_id: light.ceiling

enabled can also be a limited template, which can’t use the state of entities. In a blueprintA blueprint is a script, automation, or template entity configuration with certain parts marked as configurable. This allows you to create multiple scripts, automations, or template entities based on the same blueprint, with each having its own configuration-specific settings. Blueprints are shared by the community on the blueprints exchange in the forum. [Learn more], it can be a blueprint input. Home Assistant checks the value each time the step is about to run.

actions:
  - delay: "0:35"
    enabled: !input input_boolean