ha-service-actions

Home Assistant Service Actions

Service calls (now called "actions" in the UI) are the primary mechanism for controlling devices. Register them in async_setup, not async_setup_entry.

Python Service Calls

await hass.services.async_call(
    domain="light",
    service="turn_on",
    service_data={"brightness_pct": 80, "color_temp_kelvin": 3000},
    target={"entity_id": "light.living_room"},
    blocking=True,  # Wait for completion
)

Targeting

# Multiple entities
target={"entity_id": ["light.kitchen", "light.hallway"]}

# By area
target={"area_id": "living_room"}

# By device
target={"device_id": "abc123def456"}

Registering Custom Actions

Register in async_setup (not async_setup_entry). This data-level action targets entities, so do not declare entity_id in the vol schema — let target-based entity-service registration (see §Entity-Level Actions) resolve it, matching the services.yaml target block below and §Targeting Guidelines:

import voluptuous as vol
from homeassistant.core import HomeAssistant, ServiceCall
from homeassistant.helpers import config_validation as cv
from homeassistant.helpers.typing import ConfigType

from .const import DOMAIN

async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
    async def handle_set_mode(call: ServiceCall) -> None:
        mode = call.data["mode"]
        # Process the action...

    hass.services.async_register(
        DOMAIN,
        "set_mode",
        handle_set_mode,
        schema=vol.Schema({
            vol.Required("mode"): vol.In(["auto", "manual", "eco"]),
        }),
    )
    return True

Entry-Level (Connection/Account) Actions

For an action that operates on a connection or account, follow the IQS action-setup rule (Bronze): register actions in async_setup, accept a config_entry_id, look up the entry, and raise ServiceValidationError if it is missing or not loaded. See developers.home-assistant.io/docs/core/integration-quality-scale/rules/action-setup.