Automation triggers

A trigger is the part of an automation that makes the automation start when something specific happens, for example, when the sun sets, a door opens, or a button is pressed. You add triggers in the When section of the automation editor.

When a trigger reacts, the automation starts: Home Assistant checks the conditions, and if they are met, performs the actions. Each run is recorded in a trace, which shows which trigger started it.

Triggers react at a specific moment

A trigger reacts at a specific moment, not while something is true. For example, a trigger for a door that opens reacts when the door goes from closed to open. It doesn’t react again while the door stays open. If the door is already open when you save the automation, the trigger doesn’t react until the door closes and opens again.

If an automation should only do something while something is true, combine a trigger for the change with a condition for the situation. For examples, refer to Triggers react to changes. For which changes count, refer to What counts as a change.

What can trigger an automation

Almost anything that happens in your home or in Home Assistant can be a trigger, for example:

• A device or entity changes: a door opens, motion is detected, a temperature rises above a value.
• Time passes: a specific time of day, a repeating interval, sunrise, or sunset.
• Something happens: a button is pressed, a tag is scanned, Home Assistant starts, or a webhook is called.
• You say something to Assist: a sentence that you define.

For a list of all triggers, refer to All triggers. The general triggers, which work with any entity or event, are described in Types of triggers.

Choosing a trigger

After you select Add trigger in the automation editor, Home Assistant shows triggers that match the target or type that you selected. For many devices and measurements, the best choice is the trigger named after the thing you want to happen. For example, select Door opened for a door sensor, Temperature crossed threshold for a temperature reading, or Power crossed threshold for a power reading.

These specific triggers handle Home Assistant details for you. Measurement triggers, such as temperature and power triggers, compare compatible units automatically. For example, a temperature sensor can report in Fahrenheit while the trigger threshold is set in Celsius.

General triggers, such as State changed and Numeric state crossed threshold, are still available. Use them when you need to watch an exact state, use an attribute, work with a trigger that does not have a more specific option, or edit existing YAML.

Using several triggers

An automation can have more than one trigger. Any of them can start the automation. If the automation is still running when a trigger reacts, its mode decides what happens. To do different things depending on which trigger reacted, give each trigger an ID, and check it with a Triggered by condition. For the steps, refer to Creating an automation with actions that depend on different triggers.

One trigger can also watch several targets, for example, all lights in a room. Its Trigger when option decides whether it reacts each time one of the targets changes, only for the first one, until all targets have changed back, or once all targets have made the change. For details, refer to Understanding automations.

To start an automation only when two things are both true, add a trigger for each change, and a condition for each of the two things. For an example, refer to when two things must both be true.

In YAML, list each trigger under triggers. Any of them can start the automation:

automation:
  triggers:
    - trigger: time_pattern
      minutes: 5
    - trigger: sun
      event: sunset

To watch several entities with one trigger, list them under entity_id. The trigger reacts when any of the entities changes:

automation:
  triggers:
    - trigger: state
      entity_id:
        - sensor.one
        - sensor.two
        - sensor.three

Elements of a trigger in YAML

The main elements of a trigger that are defined in the configuration.yaml file are:

• trigger ID
• trigger variables.

Trigger ID

All triggers can be assigned an optional id. If the ID is omitted, it will instead be set to the index of the trigger. The id can be referenced from trigger conditions and actions. The id does not have to be unique for each trigger, and it can be used to group similar triggers for use later in the automation (such as several triggers of different types that should all turn some entity on).

Trigger IDs also allow you to set up an automation with many actions, each action depending on a different trigger. An action is connected to a trigger through the trigger ID, and only runs if that trigger reacted. For the steps in the editor, refer to Creating an automation with actions that depend on different triggers.

YAML example

automation:
  triggers:
    - trigger: event
      event_type: "MY_CUSTOM_EVENT"
      id: "custom_event"
    - trigger: mqtt
      topic: "living_room/switch/ac"
      id: "ac_on"
    - trigger: state  # This trigger will be assigned id="2"
      entity_id:
        - device_tracker.paulus
        - device_tracker.anne_therese
      to: "home"

Trigger variables

There are two different types of variables available for triggers. Both work like script level variables.

The first variant allows you to define variables that are set when the trigger reacts. The variables will be able to use templates and have access to the trigger variable.

The second variant is setting variables that are available when attaching a trigger when the trigger can contain templated values. These are defined using the trigger_variables key at an automation level. These variables can only contain limited templates. The triggers will not re-apply if the value of the template changes. Trigger variables are a feature meant to support using blueprint inputs in triggers.

automation:
  trigger_variables:
    my_event: example_event
  triggers:
    - trigger: event
      # Able to use `trigger_variables`
      event_type: "{{ my_event }}"
      # These variables are evaluated and set when this trigger reacts
      variables:
        name: "{{ trigger.event.data.name }}"

Types of triggers

Each trigger has a type that depends on the target of the trigger, usually corresponding to the domainEach integration in Home Assistant has a unique identifier: The domain. It is often shown as the first part (before the dot) of entity IDs. of the target.

For an overview of every trigger across all integrations, see the triggers reference.

Event trigger

For setup steps, YAML options, and examples for the event trigger, see Event trigger.

Geolocation trigger

For setup steps, YAML options, and examples for the geolocation trigger, see Geolocation trigger.

Home Assistant trigger

For setup steps, YAML options, and examples for the Home Assistant trigger, see Home Assistant trigger.

MQTT trigger

For setup steps, YAML options, and examples for the MQTT trigger, see MQTT trigger.

Numeric state crossed threshold trigger

For setup steps, YAML options, and examples for the Numeric state crossed threshold trigger, see Numeric state crossed threshold trigger.

Sentence trigger

For setup steps, YAML options, and examples of a sentence trigger, see Sentence triggers.

Sentence wildcards

For wildcard syntax and examples, see Sentence wildcards.

State changed trigger

For setup steps, YAML options, and examples for the State changed trigger, see State changed trigger.

Sun trigger

Sunset and Sunrise trigger

Reacts when the sun is setting or rising—that is, when the sun elevation reaches 0°.

An optional time offset can be given to have it react a set time before or after the sun event (for example, 45 minutes before sunset). A negative value makes it react before sunrise or sunset, a positive value afterwards. The offset needs to be specified in number of seconds, or in a hh:mm:ss format.

automation:
  triggers:
    - trigger: sun
      # Possible values: sunset, sunrise
      event: sunset
      # Optional time offset. This example will trigger 45 minutes before sunset.
      offset: "-00:45:00"

Sun elevation trigger

Sometimes you may want more granular control over an automation than simply sunset or sunrise and specify an exact elevation of the sun. This can be used to layer automations to occur as the sun lowers on the horizon or even after it is below the horizon. This is also useful when the “sunset” event is not dark enough outside and you would like the automation to run later at a precise solar angle instead of the time offset such as turning on exterior lighting. For most automations intended to run during dusk or dawn, a number between 0° and -6° is suitable; -4° is used in this example:

automation:
  - alias: "Exterior Lighting on when dark outside"
    triggers:
      - trigger: numeric_state
        entity_id: sun.sun
        attribute: elevation
        # Can be a positive or negative number
        below: -4.0
    actions:
      - action: switch.turn_on
        target:
          entity_id: switch.exterior_lighting

If you want to get more precise, you can use this solar calculator, which will help you estimate what the solar elevation will be at any specific time. Then from this, you can select from the defined twilight numbers.

Although the actual amount of light depends on weather, topography and land cover, they are defined as:

• Civil twilight: 0° > Solar angle > -6°

  This is what is meant by twilight for the average person: Under clear weather conditions, civil twilight approximates the limit at which solar illumination suffices for the human eye to clearly distinguish terrestrial objects. Enough illumination renders artificial sources unnecessary for most outdoor activities.

• Nautical twilight: -6° > Solar angle > -12°

• Astronomical twilight: -12° > Solar angle > -18°

A very thorough explanation of this is available in the Wikipedia article about the Twilight.

Tag trigger

Reacts when a tag is scanned. For example, an NFC tag is scanned using the Home Assistant Companion mobile application.

automation:
  triggers:
    - trigger: tag
      tag_id: A7-6B-90-5F

Additionally, you can also only trigger if a card is scanned by a specific device/scanner by setting the device_id:

automation:
  triggers:
    - trigger: tag
      tag_id: A7-6B-90-5F
      device_id: 0e19cd3cf2b311ea88f469a7512c307d

Or trigger on multiple possible devices for multiple tags:

automation:
  triggers:
    - trigger: tag
      tag_id:
        - "A7-6B-90-5F"
        - "A7-6B-15-AC"
      device_id:
        - 0e19cd3cf2b311ea88f469a7512c307d
        - d0609cb25f4a13922bb27d8f86e4c821

Template trigger

Template triggers work by evaluating a template when any of the recognized entities change state. The trigger reacts if the state change caused the template to render ‘true’ (a non-zero number or any of the strings true, yes, on, enable) when it was previously ‘false’ (anything else).

This is achieved by having the template result in a true boolean expression (for example {{ is_state('device_tracker.paulus', 'home') }}) or by having the template render true (example below).

With template triggers you can also evaluate attribute changes by using is_state_attr (like {{ is_state_attr('climate.living_room', 'away_mode', 'off') }})

automation:
  triggers:
    - trigger: template
      value_template: "{% if is_state('device_tracker.paulus', 'home') %}true{% endif %}"

      # If given, will trigger when template remains true for X time.
      for: "00:01:00"

You can also use templates in the for option.

automation:
  triggers:
    - trigger: template
      value_template: "{{ is_state('device_tracker.paulus', 'home') }}"
      for:
        minutes: "{{ states('input_number.minutes')|int(0) }}"

The for template(s) will be evaluated when the value_template becomes ‘true’.

Templates that do not contain an entity will be rendered once per minute.

Time pattern trigger

With the time pattern trigger, you can match if the hour, minute or second of the current time matches a specific value. You can prefix the value with a / to match whenever the value is divisible by that number. You can specify * to match any value.

automation:
  triggers:
    - trigger: time_pattern
      # Matches every hour at 5 minutes past whole
      minutes: 5

automation 2:
  triggers:
    - trigger: time_pattern
      # Trigger once per minute during the hour of 3
      hours: "3"
      minutes: "*"

automation 3:
  triggers:
    - trigger: time_pattern
      # You can also match on interval. This will match every 5 minutes
      minutes: "/5"

Time trigger

For setup steps, YAML options, and examples for the time trigger, see Time trigger.

Webhook trigger

Webhook trigger reacts 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. The webhook_id can either be a static value or computed using limited templates.

automation:
  trigger_variables:
    webhook_id_variable: "template_webhook_id"
  triggers:
    - trigger: webhook
      webhook_id: "some_hook_id"
      allowed_methods:
        - POST
        - PUT
      local_only: true
    - trigger: webhook
      webhook_id: "{{ webhook_id_variable }}"
      allowed_methods:
        - POST

You can run this automation by sending an HTTP POST request to http://your-home-assistant:8123/api/webhook/some_hook_id. Here is an example using the curl command line program, with an example form data payload:

curl -X POST -d 'key=value&key2=value2' https://your-home-assistant:8123/api/webhook/some_hook_id

Webhooks support HTTP POST, PUT, HEAD, and GET requests; PUT requests are recommended. HTTP GET and HEAD requests are not enabled by default but can be enabled by adding them to the allowed_methods option. The request methods can also be configured in the UI by selecting the settings gear menu button beside the Webhook ID.

By default, webhook triggers can only be accessed from devices on the same network as Home Assistant or via Nabu Casa Cloud webhooks. The local_only option should be set to false to allow webhooks to be triggered directly via the internet. This option can also be configured in the UI by selecting the settings gear menu button beside the Webhook ID.

Remember to use an HTTPS URL if you’ve secured your Home Assistant installation with SSL/TLS.

Note that a given webhook can only be used in one automation at a time. That is, only one automation trigger can use a specific webhook ID.

Webhook data

Payloads may either be encoded as form data or JSON. Depending on that, its data will be available in an automation template as either trigger.data or trigger.json. URL query parameters are also available in the template as trigger.query.

Note that to use JSON encoded payloads, the Content-Type header must be set to application/json, for example:

curl -X POST -H "Content-Type: application/json" -d '{ "key": "value" }' https://your-home-assistant:8123/api/webhook/some_hook_id

Webhook security

Webhook endpoints don’t require authentication, other than knowing a valid webhook ID. Security best practices for webhooks include:

• Do not use webhooks to trigger automations that are destructive, or that can create safety issues. For example, do not use a webhook to unlock a lock, or open a garage door.
• Treat a webhook ID like a password: use a unique, non-guessable value, and keep it secret.
• Do not copy-and-paste webhook IDs from public sources, including blueprints. Always create your own.
• Keep the local_only option enabled for webhooks if access from the internet is not required.

Zone trigger

Zone trigger reacts when an entity is entering or leaving the zone. The entity can be either a person or a device tracker.

automation:
  triggers:
    - trigger: zone
      entity_id: person.paulus
      zone: zone.home
      # Event is either enter or leave
      event: enter # or "leave"

Unavailable and unknown state behavior in triggers

Most triggers that have an entity as the target do not react when an entity transitions from an unavailable or unknown state. For example, if a light goes offline and comes back on, the light.turned_on trigger does not react to that recovery. The State changed trigger does react to that change, for example, from unavailable to on.

Disabling a trigger

Every individual trigger in an automation can be disabled, without removing it. To do so, add enabled: false to the trigger. For example:

# Example script with a disabled trigger
automation:
  triggers:
    # This trigger will not trigger, as it is disabled.
    # This automation does not run when the sun is set.
    - enabled: false
      trigger: sun
      event: sunset

    # This trigger reacts, as it is not disabled.
    - trigger: time
      at: "15:32:00"

Triggers can also be disabled based on limited templates or blueprint inputs. These are only evaluated once when the automation is loaded.

blueprint:
  input:
    input_boolean:
      name: Boolean
      selector:
        boolean:
    input_number:
      name: Number
      selector:
        number:
          min: 0
          max: 100

  trigger_variables:
    _enable_number: !input input_number

  triggers:
    - trigger: sun
      event_type: sunrise
      enabled: !input input_boolean
    - trigger: sun
      event_type: sunset
      enabled: "{{ _enable_number < 50 }}"

Merging lists of triggers

In some cases, like when using blueprints with trigger selectors, you may need to insert a second list of triggers into the main trigger list. You can do this by adding a dictionary in the main trigger list with only the triggers key, and the value for that key contains a second list of triggers. These will then be flattened into a single list of triggers. For example:

blueprint:
  name: Nested Trigger Blueprint
  domain: automation
  input:
    usertrigger:
      selector:
        trigger:

triggers:
  - trigger: event
    event_type: manual_event
  - triggers: !input usertrigger

This blueprint automation can then be triggered either by the fixed manual_event trigger, or additionally by any triggers selected in the trigger selector. This is also applicable for wait_for_trigger action.

Creating an automation with actions that depend on different triggers

Instead of creating many automations for different groups of related triggers and actions, you can build a single one in the visual editor of the UI by following the steps below.

1. Go to Settings > Automations & scenes.
2. In the lower right corner, select Create automation > Create new automation.
3. In the When section, select Add trigger.
4. Search for the trigger using the search box, for example, and then select it.
5. In the trigger window on the right, edit the Trigger ID by going to the three dots menu > Edit ID.
6. In the Then do section, select Add action and then select the Choose block.
7. Expand the option section, select Add condition and, from the By type list, select the Triggered by condition.
8. In the condition window on the right, select the trigger ID that you added in step 5 and then Save.
9. In the section of the same option, select Add action and choose the action that runs for the related trigger.
10. In the action window on the right, select the target or group of targets, input any other requested data and select Save.
11. You can add more conditions and actions to that option by repeating steps 6 to 10.
12. Repeat steps 3 to 11 to add another trigger and related option for the new condition and action.