Service calls


Various integrations allow calling servicesA service carries out one specific task, for example: turn on the light in the living room. A service has targets and data and can be called by actions, a dashboard, or via voice command.
[Learn more]
when a certain event occurs. The most common one is calling a service when an automation triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run.
[Learn more]
happens. But a service can also be called from a scriptScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on.
[Learn more]
, a dashboard or via voice command devices such as Amazon Echo.

The configuration options to call a configuration 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.

Use the "Services" tab under Developer Tools to discover available services.

The basics

Call the service 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]
group.living_room. This will turn all members of group.living_room on. You can also use entity_id: all and it will turn on all possible entities.

service: homeassistant.turn_on
entity_id: group.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 are meant to match areas (or rooms) in the physical world: your home. For example, the living room area groups devices and entities in your living room. 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: area_id, device_id, entity_id. Each of these can be a list.

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

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

Passing data to the service call

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

service: light.turn_on
entity_id: group.living_room
data:
  brightness: 120
  rgb_color: [255, 0, 0]

A full list of the parameters for a service can be found on the documentation page of each integration, in the same way as it’s done for the light.turn_on service.

Use templates to decide which service to call

You can use templating support to dynamically choose which service to call. For example, you can call a certain service based on if a light is on.

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

Using the Services Developer Tool

You can use the Services Developer Tool to test data to pass in a service call. For example, you may test turning on or off a ‘group’ (See [groups] for more info)

To turn a group on or off, pass the following info:

  • Domain: homeassistant
  • Service: turn_on
  • Service Data: { "entity_id": "group.kitchen" }

Use templates to determine the attributes

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

service: thermostat.set_temperature
target:
  entity_id: >
    {% if is_state('device_tracker.paulus', 'home') %}
      thermostat.upstairs
    {% else %}
      thermostat.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.

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

Use templates to handle response data

Some services may respond with data that can be used in automation. This data is called service response data. Service 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 service response data are upcoming calendar events for the next week or detailed driving directions.

Templates can also be used for handling response data. The service call 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 calls a service and stores the response in the variable called agenda.

service: 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.

Which data fields can be used in a service call depends on the type of notification service that is used.
service: notify.gmail_com
data:
  target: "[email protected]"
  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 services

There are four homeassistant services that aren’t tied to any single domain, these are:

  • homeassistant.turn_on - Turns on an entity (that supports being turned on), for example an automation, switch, etc.
  • homeassistant.turn_off - Turns off an entity (that supports being turned off), for example an automation, switch, etc.
  • 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 - Request the update of an entity, rather than waiting for the next scheduled update, for example Google travel time sensor, a template sensor, or a light

Complete service details and examples can be found on the Home Assistant integration page.