Performing actions

Various integrations allow performing actionsAn action makes Home Assistant do something, for example, turn on a light, send a notification, or activate a scene. Automations and scripts run a list of actions. [Learn more] when a certain event occurs. The most common one is performing an action when an automation triggerA trigger is the part of an automation that makes the automation run when a specific change happens, for example, when the sun sets or a door opens. [Learn more] happens. But an action can also be called from a scriptA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more], a dashboard, or via voice command devices such as Amazon Echo.

The configuration options to perform action are the same between all integrations and are described on this page.

Examples on this page will be given as part of an automation integration configuration but different approaches can be used for other integrations too.

The basics

Perform the action homeassistant.turn_on on the entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] light.living_room, which is a light group. This turns on every light that is a member of the group. You can also use entity_id: all and it will turn on all possible entities.

action: homeassistant.turn_on
target:
  entity_id: light.living_room

Targeting areas and devices

Instead of targeting an entity, you can also target an areaAn area in Home Assistant is a logical grouping of devices and entities that represents a room or space in your home, such as the living room, kitchen, or garage. [Learn more] or deviceA device is a model representing a physical or logical unit that contains entities.. Or a combination of these. This is done with the target key.

A target is a map that contains at least one of the following: entity_id, device_id, area_id, floor_id, or label_id. Each of these can be a list. The values should be lower-cased.

The following example uses a single action to turn on the lights in the living room area, 2 additional light devices and 2 additional light entities:

action: light.turn_on
target:
  area_id: living_room
  device_id:
    - ff22a1889a6149c5ab6327a8236ae704
    - 52c050ca1a744e238ad94d170651f96b
  entity_id:
    - light.hallway
    - light.landing

Passing data to the action

You can also specify other parameters beside the entity to target. For example, the light.turn_on action allows specifying the brightness.

action: light.turn_on
target:
  entity_id: light.living_room
data:
  brightness: 120
  rgb_color:
    - 255
    - 0
    - 0

Each action has its own page with all its options, for example, Turn on light. For all actions, refer to the list of available actions.

Use templates to decide which action to perform

You can use templating support to dynamically choose which action to perform. For example, you can turn a switch on or off based on the temperature.

action: >
  {% if states('sensor.temperature') | float(15) > 15 %}
    switch.turn_on
  {% else %}
    switch.turn_off
  {% endif %}
target:
  entity_id: switch.ac

Testing an action in Tools

To try an action and its data before you use it in an automation or a script, use the Actions tab in Settings > Tools > Actions. For the steps, refer to the Actions tab.

Use templates to determine the attributes

Templates can also be used for the data that you pass to the action.

action: climate.set_temperature
target:
  entity_id: >
    {% if is_state('device_tracker.paulus', 'home') %}
      climate.upstairs
    {% else %}
      climate.downstairs
    {% endif %}
data:
  temperature: "{{ 22 - distance(states.device_tracker.paulus) }}"

You can use a template returning a native dictionary as well, which is useful if the attributes to be set depend on the situation.

action: climate.set_temperature
data: >
  {% if states('sensor.temperature_living') | float(19) < 19 %}
    {"hvac_mode": "heat", "temperature": 19 }
  {% else %}
    {"hvac_mode": "auto" }
  {% endif %}

Use templates to handle response data

Some actions may respond with data that can be used in automation. This data is called action response data. Action response data is typically used for data that is dynamic or large and which may not be suited for use in entity state. Examples of action response data are upcoming calendar events for the next week or detailed driving directions.

Templates can also be used for handling response data. The action can specify a response_variable. This is the variable that contains the response data. You can define any name for your response_variable. This example performs an action and stores the response in the variable called agenda.

action: calendar.get_events
target:
  entity_id: calendar.school
data:
  duration:
    hours: 24
response_variable: agenda

You may then use the response data in the variable agenda in another action in the same script. The example below sends a notification using the response data.

action: notify.gmail_com
data:
  target: "gduser1@workspacesamples.dev"
  title: "Daily agenda for {{ now().date() }}"
  message: >-
    Your agenda for today:
    <p>
    {% for event in agenda['calendar.school'].events %}
    {{ event.start}}: {{ event.summary }}<br>
    {% endfor %}
    </p>

homeassistant actions

The homeassistant integration provides four actions that work on entities of any domain:

• homeassistant.turn_on: Turns on an entity (that supports being turned on), such as an automation or switch.
• homeassistant.turn_off: Turns off an entity (that supports being turned off), such as an automation or switch.
• homeassistant.toggle: Turns off an entity that is on, or turns on an entity that is off (that supports being turned on and off).
• homeassistant.update_entity: Requests the update of an entity, rather than waiting for the next scheduled update, for example, a Google travel time sensor, a template sensor, or a light.

The homeassistant integration also provides other actions, for example, to restart Home Assistant or to reload parts of the configuration. For all of them, with details and examples, refer to the Home Assistant integration page.