Prompt file imported from pantherale0/ha-hellofresh (.github/prompts/Add Action.prompt.md). Copyright stays with the author.

Add Service Action

Name: Add Action
Author: pantherale0

Your goal is to add a new service action to this Home Assistant integration that users can call from automations, scripts, or the UI.

Terminology:

Developer/Code: "service action" (e.g., function names, comments, documentation)
User-facing: "action" only (e.g., in UI, translations under actions key)
Legacy: services.yaml, hass.services.async_register(), ServiceCall class (internal API)

If not provided, ask for:

Service action name and purpose
Parameters required (with types and validation)
What the service action does (API call, state change, etc.)
Response data (if any)
Target: device, entity, or integration-wide

Implementation Steps

1. Define Service Action in `services.yaml`

File: custom_components/{domain}/services.yaml

Note: services.yaml is a legacy filename from when these were called "services". We now call them "service actions" in code and "actions" for users.

CRITICAL: Per HA documentation, action names and descriptions must be defined in translation files under the actions key (not services), NOT in services.yaml. The services.yaml file only defines the schema.

Add service action definition:

[action_name]:
  # Use translation_key to reference translations
  translation_key: [action_name]

  # For device or entity-targeted service actions
  target:
    entity:
      domain: [platform] # sensor, switch, etc.
      # OR
      integration: { domain }

  # Service action parameters - organize with sections for better UX
  fields:
    # SECTION: Basic parameters
    [parameter_name]:
      translation_key: [parameter_name]
      required: true
      example: "[example value]"
      selector:
        text:
          # OR number:, boolean:, select:, etc.

    [another_parameter]:
      translation_key: [another_parameter]
      required: false
      default: [default value]
      selector:
        number:
          min: 0
          max: 100
          mode: slider

    # Advanced section (appears collapsed by default)
    advanced:
      collapsed: true
      fields:
        [advanced_parameter]:
          translation_key: [advanced_parameter]
          required: false
          selector:
            boolean:

With sections for better organization:

[action_name]:
  # No name/description - translations only!

  target:
    entity:
      integration: { domain }

  fields:
    # Basic section - always visible
    basic:
      # Section names come from translations: actions.[action_name].sections.basic.name
      collapsed: false
      icon: mdi:cog-outline
      fields:
        [parameter_name]:
          # Field names come from translations: actions.[action_name].fields.[parameter_name].name
          required: true
          selector:
            text:

    # Advanced section - collapsed by default
    advanced:
      # Section names come from translations: actions.[action_name].sections.advanced.name
      collapsed: true
      icon: mdi:tune-vertical
      fields:
        [advanced_parameter]:
          # Field names come from translations: actions.[action_name].fields.[advanced_parameter].name
          required: false
          selector:
            boolean:

Special case: translation_key in selectors

Use translation_key only for select selectors with dynamic options:

fields:
  preset_mode:
    selector:
      select:
        translation_key: "fan_speed" # Only needed here!
        options:
          - "off"
          - "low"
          - "medium"
          - "high"

This allows translating the option labels via selector.[translation_key].options.[option_value] in translations.

Best Practices for Schema Definition:

Always add icons - Provide meaningful icons for sections AND individual fields where applicable
- Sections: icon: mdi:cog-outline (basic), icon: mdi:tune-vertical (advanced)
- Fields: Consider field type and purpose (e.g., mdi:timer for duration, mdi:thermometer for temperature)
Always add descriptions - Provide descriptions wherever the schema allows (sections, fields)
- Makes the UI more user-friendly
- Helps users understand what each parameter does
Markdown support - Be aware of where markdown is supported:
- ✅ Service action descriptions - Markdown is supported
- ✅ Section descriptions - Markdown is supported
- ❌ Field names - Plain text only (keep short, 2-4 words)
- ✅ Field descriptions - Markdown is supported (can use **bold**, [links](url), etc.)
- Use markdown for formatting longer descriptions, links to documentation, etc.
Choose text appropriately:
- Names: Short, concise labels (2-4 words)
- Descriptions: Detailed explanations with examples, constraints, or links
- Use field descriptions to explain valid ranges, formats, or special behavior

Reference: Home Assistant Services Documentation

2. Create Service Action Handler

Directory naming: Use service_actions/ for new code (preferred) or actions/ (acceptable). Be consistent within your integration.

Option A: Simple service action in service_actions/ directory

Create custom_components/{domain}/service_actions/[action_name].py:

"""[Action name] service action for [Integration Title]."""

from __future__ import annotations

import logging
from typing import Any

import voluptuous as vol

from homeassistant.core import HomeAssistant, ServiceCall, SupportsResponse
from homeassistant.helpers import config_validation as cv

from ..const import DOMAIN

_LOGGER = logging.getLogger(__name__)

# Action parameter constants
ATTR_PARAMETER = "parameter_name"

# Action schema for validation
SERVICE_SCHEMA = vol.Schema(
    {
        vol.Required(ATTR_PARAMETER): cv.string,
        # Add more parameters with validators
        vol.Optional("optional_param", default=100): cv.positive_int,
    }
)


async def async_setup_service_action(hass: HomeAssistant) -> None:
    """Set up the [action_name] service action."""

    async def async_handle_service_action(call: ServiceCall) -> None:
        """Handle the service action call."""
        # Extract parameters
        parameter_value = call.data[ATTR_PARAMETER]
        optional_value = call.data.get("optional_param", 100)

        _LOGGER.debug(
            "Service action [action_name] called with: %s=%s",
            ATTR_PARAMETER,
            parameter_value,
        )

        # Get coordinator or API client from hass.data
        # For each config entry that this service action applies to:
        for entry_id, entry_data in hass.data[DOMAIN].items():
            coordinator = entry_data  # Or entry_data["coordinator"]

            try:
                # Perform the action action
                await coordinator.api_client.do_something(parameter_value)

                # Optionally refresh data
                await coordinator.async_request_refresh()

            except Exception as err:
                _LOGGER.error(
                    "Error executing service action [action_name]: %s",
                    err,
                )
                # Consider raising HomeAssistantError for user visibility

    # Register the service action (legacy API uses hass.services)
    hass.services.async_register(  # Legacy API: hass.services, not hass.actions
        DOMAIN,
        "[action_name]",
        async_handle_service_action,
        schema=SERVICE_SCHEMA,
    )

Option B: Entity-targeted service action

async def async_handle_entity_service_action(entity, call: ServiceCall) -> None:
    """Handle service action call for specific entity."""
    parameter_value = call.data[ATTR_PARAMETER]

    # Entity has access to coordinator
    await entity.coordinator.api_client.do_something(
        entity.device_id,
        parameter_value,
    )
    await entity.coordinator.async_request_refresh()


async def async_setup_service_action(hass: HomeAssistant) -> None:
    """Set up entity-targeted service action."""
    platform = entity_platform.async_get_current_platform()

    platform.async_register_entity_service(  # Note: uses 'service', not 'action'
        "[action_name]",
        SERVICE_SCHEMA,
        async_handle_entity_service_action,
    )

3. Register Service Action in `init.py`

File: custom_components/{domain}/__init__.py

CRITICAL: Service actions must register in async_setup or setup, NOT in async_setup_entry!

Service actions are integration-wide, not per config entry.

from .service_actions.[action_name] import async_setup_service_action as async_setup_[action_name]_service_action

async def async_setup(hass: HomeAssistant, config: dict) -> bool:
    """Set up the integration."""
    # Register integration-wide service actions (only once for entire integration)
    await async_setup_[action_name]_service_action(hass)

    return True


async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Set up from a config entry."""
    # ... existing setup code ...
    # DO NOT register service actions here!

    return True

For platform-specific service actions (entity service actions):

# In sensor/__init__.py or other platform
from homeassistant.helpers import entity_platform

async def async_setup_entry(...) -> None:
    """Set up platform."""
    # ... add entities ...

    # Register entity service actions
    platform = entity_platform.async_get_current_platform()

    from ..service_actions.[action_name] import (
        SERVICE_SCHEMA,
        async_handle_entity_service_action,
    )

    platform.async_register_entity_service(  # Uses 'service', not 'action'
        "[action_name]",
        SERVICE_SCHEMA,
        async_handle_entity_service_action,
    )

4. Add Service Action Constants

File: custom_components/{domain}/const.py

# Service action names (use SERVICE_ prefix for legacy compatibility)
SERVICE_[SERVICE_NAME] = "[action_name]"

# Service action parameters
ATTR_[PARAMETER_NAME] = "[parameter_name]"

5. Add Translations

CRITICAL: All action names, descriptions, and field labels MUST be in translation files under the services key. Per HA documentation, services.yaml contains only the schema, not user-facing text. Note: The key is services (legacy) even though they are called "service actions" in documentation and "actions" in the UI.

translations/en.json:

{
  "services": {
    "[action_name]": {
      "name": "[Action Name]",
      "description": "[Detailed description with **markdown** support. Can include [links](https://example.com) and formatting.]",
      "sections": {
        "basic": {
          "name": "Basic Settings",
          "description": "Essential parameters. You can use **markdown** here to highlight important information."
        },
        "advanced": {
          "name": "Advanced Settings",
          "description": "Optional advanced configuration. See [documentation](https://example.com) for details."
        }
      },
      "fields": {
        "[parameter_name]": {
          "name": "Parameter Name",
          "description": "Detailed explanation of what this parameter does. **Supports markdown**, can include ranges like `0-100`, examples, or [links](https://example.com)."
        },
        "[another_parameter]": {
          "name": "Another Parameter",
          "description": "Another detailed description. Explain valid values, constraints, and behavior."
        },
        "[advanced_parameter]": {
          "name": "Advanced Parameter",
          "description": "Advanced parameter description with technical details."
        }
      }
    }
  }
}

translations/de.json:

{
  "services": {
    "[action_name]": {
      "name": "[German Action Name]",
      "description": "[Detaillierte Beschreibung mit **Markdown**-Unterstützung. Kann [Links](https://example.com) und Formatierung enthalten.]",
      "sections": {
        "basic": {
          "name": "Grundeinstellungen",
          "description": "Wesentliche Parameter. Sie können hier **Markdown** verwenden, um wichtige Informationen hervorzuheben."
        },
        "advanced": {
          "name": "Erweiterte Einstellungen",
          "description": "Optionale erweiterte Konfiguration. Siehe [Dokumentation](https://example.com) für Details."
        }
      },
      "fields": {
        "[parameter_name]": {
          "name": "Parametername",
          "description": "Detaillierte Erklärung, was dieser Parameter tut. **Unterstützt Markdown**, kann Bereiche wie `0-100`, Beispiele oder [Links](https://example.com) enthalten."
        },
        "[another_parameter]": {
          "name": "Anderer Parameter",
          "description": "Eine weitere detaillierte Beschreibung. Erklären Sie gültige Werte, Einschränkungen und Verhalten."
        },
        "[advanced_parameter]": {
          "name": "Erweiterter Parameter",
          "description": "Beschreibung des erweiterten Parameters mit technischen Details."
        }
      }
    }
  }
}

Translation structure:

services.[action_name].name - Action display name (required)
services.[action_name].description - Action description (required)
services.[action_name].sections.[section_key].name - Section heading (if using sections)
services.[action_name].sections.[section_key].description - Section description (optional)
services.[action_name].fields.[parameter_name].name - Field label (required)
services.[action_name].fields.[parameter_name].description - Field description (required)

When translation_key is needed:

Only use translation_key in services.yaml for select selectors with dynamic options:

{
  "selector": {
    "fan_speed": {
      "options": {
        "off": "Off",
        "low": "Low",
        "medium": "Medium",
        "high": "High"
      }
    }
  }
}

This maps to selector: select: translation_key: "fan_speed" in services.yaml.

6. Add Response Data (Optional)

If service action returns data:

from homeassistant.core import SupportsResponse

# In service action handler
async def async_handle_service_action(call: ServiceCall) -> dict[str, Any]:
    """Handle service action and return data."""
    result = await do_something()

    # Return response data
    return {
        "success": True,
        "value": result,
    }

# When registering
hass.services.async_register(  # Legacy API: hass.services
    DOMAIN,
    "[action_name]",
    async_handle_service_action,
    schema=SERVICE_SCHEMA,
    supports_response=SupportsResponse.OPTIONAL,  # OPTIONAL: may return data | ONLY: always returns data
)

SupportsResponse values:

NONE (default): Service action does not return data
OPTIONAL: Service action may conditionally return data
ONLY: Service action always returns data

7. Field Filtering by supported_features (Advanced)

For entity actions with dynamic fields based on capabilities:

# In services.yaml
[action_name]:
  target:
    entity:
      domain: fan
  fields:
    preset_mode:
      # Only show if entity has PRESET_MODE feature
      filter:
        supported_features:
          - fan.FanEntityFeature.PRESET_MODE
      selector:
        select:
          options: [] # Entity provides options dynamically

8. Action Icons (2025 Best Practice)

CRITICAL: Define icons for actions, sections, AND fields for better UX.

icons.json:

{
  "actions": {
    "[action_name]": {
      "service": "mdi:icon-name",
      "sections": {
        "basic": "mdi:cog-outline",
        "advanced": "mdi:tune-vertical"
      }
    }
  }
}

Icon selection tips:

Choose meaningful, recognizable icons from Material Design Icons
Actions: Use action-specific icons (e.g., mdi:restart, mdi:update, mdi:cog-play)
Sections: mdi:cog-outline (basic/general), mdi:tune-vertical (advanced/fine-tuning)
Fields: Consider in services.yaml if field needs visual distinction (e.g., mdi:timer, mdi:thermometer)

Service Action Types

Integration-Wide Service Action

Applies to all devices/entries
Example: Refresh all devices, reset cache

Device-Targeted Service Action

Uses target.device selector
Applies to specific device
Example: Reboot device, update firmware

Entity-Targeted Service Action

Uses target.entity selector
Applies to specific entity
Example: Set mode, calibrate sensor

Validation Patterns

Common Validators

import voluptuous as vol
from homeassistant.helpers import config_validation as cv

SERVICE_SCHEMA = vol.Schema({
    vol.Required("string_param"): cv.string,
    vol.Required("int_param"): cv.positive_int,
    vol.Required("float_param"): vol.Range(min=0.0, max=100.0),
    vol.Required("bool_param"): cv.boolean,
    vol.Required("time_param"): cv.time,
    vol.Required("entity_id"): cv.entity_id,
    vol.Required("enum_param"): vol.In(["option1", "option2", "option3"]),
    vol.Optional("optional_param", default="default"): cv.string,
})

Custom Validator

def validate_custom(value: Any) -> Any:
    """Validate custom parameter."""
    if not meets_criteria(value):
        raise vol.Invalid("Parameter does not meet criteria")
    return value

SERVICE_SCHEMA = vol.Schema({
    vol.Required("custom"): validate_custom,
})

Error Handling

from homeassistant.exceptions import HomeAssistantError

async def async_handle_service_action(call: ServiceCall) -> None:
    """Handle service action with error handling."""
    try:
        result = await do_something(call.data)

    except ConnectionError as err:
        raise HomeAssistantError(
            f"Failed to connect to device: {err}"
        ) from err

    except ValueError as err:
        raise HomeAssistantError(
            f"Invalid parameter value: {err}"
        ) from err

Validation Checklist

Testing

Start Home Assistant: script/develop
Go to Developer Tools > Actions tab (user-facing: "Actions", not "Services")
Find service action: {domain}.[action_name]
Test with valid parameters
Test with invalid parameters (should show validation errors)
Test with edge cases
Check logs for errors
Verify icons display correctly
Verify descriptions are helpful and formatted

Additional Resources

Home Assistant Services Documentation - Official developer guide
Service Translations - Translation key patterns (use services key)
Service Sections - Organizing parameters with sections

Integration Context

Domain: {domain}
Service actions directory: custom_components/{domain}/service_actions/ (preferred) or actions/
Service actions definition: custom_components/{domain}/services.yaml (legacy filename)
Icons: custom_components/{domain}/icons.json under services key (legacy)
Translations: custom_components/{domain}/translations/*.json under services key (legacy)

Follow patterns from existing service actions in the integration.

Output

After implementation:

Run script/check to validate
Start Home Assistant and test service action
Verify service action appears in UI Actions tab with proper description
Verify translations show "action" terminology for users (not "service action")
Test all parameters and edge cases
Report results

# Add Service Action Your goal is to add a new **service action** to this Home Assistant integration that users can call from automations, scripts, or the UI. **Terminology:** - **Developer/Code:** "service action" (e.g., function names, comments, documentation) - **User-facing:** "action" only (e.g., in UI, translations under `actions` key) - **Legacy:** `services.yaml`, `hass.services.async_register()`, `ServiceCall` class (internal API) If not provided, ask for: - Service action name and purpose - Parameters required (with types and validation) - What the service action does (API call, state change, etc.) - Response data (if any) - Target: device, entity, or integration-wide ## Implementation Steps ### 1. Define Service Action in `services.yaml` **File:** `custom_components/{domain}/services.yaml` **Note:** `services.yaml` is a legacy filename from when these were called "services". We now call them "service actions" in code and "actions" for users. **CRITICAL:** Per [HA documentation](https://developers.home-assistant.io/docs/dev_101_services), action names and descriptions must be defined in translation files under the `actions` key (not `services`), NOT in `services.yaml`. The `services.yaml` file only defines the schema. Add service action definition: ```yaml [action_name]: # Use translation_key to reference translations translation_key: [action_name] # For device or entity-targeted service actions target: entity: domain: [platform] # sensor, switch, etc. # OR integration: { domain } # Service action parameters - organize with sections for better UX fields: # SECTION: Basic parameters [parameter_name]: translation_key: [parameter_name] required: true example: "[example value]" selector: text: # OR number:, boolean:, select:, etc. [another_parameter]: translation_key: [another_parameter] required: false default: [default value] selector: number: min: 0 max: 100 mode: slider # Advanced section (appears collapsed by default) advanced: collapsed: true fields: [advanced_parameter]: translation_key: [advanced_parameter] required: false selector: boolean: ``` **With sections for better organization:** ```yaml [action_name]: # No name/description - translations only! target: entity: integration: { domain } fields: # Basic section - always visible basic: # Section names come from translations: actions.[action_name].sections.basic.name collapsed: false icon: mdi:cog-outline fields: [parameter_name]: # Field names come from translations: actions.[action_name].fields.[parameter_name].name required: true selector: text: # Advanced section - collapsed by default advanced: # Section names come from translations: actions.[action_name].sections.advanced.name collapsed: true icon: mdi:tune-vertical fields: [advanced_parameter]: # Field names come from translations: actions.[action_name].fields.[advanced_parameter].name required: false selector: boolean: ``` **Special case: `translation_key` in selectors** Use `translation_key` only for `select` selectors with dynamic options: ```yaml fields: preset_mode: selector: select: translation_key: "fan_speed" # Only needed here! options: - "off" - "low" - "medium" - "high" ``` This allows translating the option labels via `selector.[translation_key].options.[option_value]` in translations. **Best Practices for Schema Definition:** 1. **Always add icons** - Provide meaningful icons for sections AND individual fields where applicable - Sections: `icon: mdi:cog-outline` (basic), `icon: mdi:tune-vertical` (advanced) - Fields: Consider field type and purpose (e.g., `mdi:timer` for duration, `mdi:thermometer` for temperature) 2. **Always add descriptions** - Provide descriptions wherever the schema allows (sections, fields) - Makes the UI more user-friendly - Helps users understand what each parameter does 3. **Markdown support** - Be aware of where markdown is supported: - ✅ **Service action descriptions** - Markdown is supported - ✅ **Section descriptions** - Markdown is supported - ❌ **Field names** - Plain text only (keep short, 2-4 words) - ✅ **Field descriptions** - Markdown is supported (can use `**bold**`, `[links](url)`, etc.) - Use markdown for formatting longer descriptions, links to documentation, etc. 4. **Choose text appropriately**: - Names: Short, concise labels (2-4 words) - Descriptions: Detailed explanations with examples, constraints, or links - Use field descriptions to explain valid ranges, formats, or special behavior **Reference:** [Home Assistant Services Documentation](https://developers.home-assistant.io/docs/dev_101_services) ### 2. Create Service Action Handler **Directory naming:** Use `service_actions/` for new code (preferred) or `actions/` (acceptable). Be consistent within your integration. **Option A: Simple service action in `service_actions/` directory** Create `custom_components/{domain}/service_actions/[action_name].py`: ```python """[Action name] service action for [Integration Title].""" from __future__ import annotations import logging from typing import Any import voluptuous as vol from homeassistant.core import HomeAssistant, ServiceCall, SupportsResponse from homeassistant.helpers import config_validation as cv from ..const import DOMAIN _LOGGER = logging.getLogger(__name__) # Action parameter constants ATTR_PARAMETER = "parameter_name" # Action schema for validation SERVICE_SCHEMA = vol.Schema( { vol.Required(ATTR_PARAMETER): cv.string, # Add more parameters with validators vol.Optional("optional_param", default=100): cv.positive_int, } ) async def async_setup_service_action(hass: HomeAssistant) -> None: """Set up the [action_name] service action.""" async def async_handle_service_action(call: ServiceCall) -> None: """Handle the service action call.""" # Extract parameters parameter_value = call.data[ATTR_PARAMETER] optional_value = call.data.get("optional_param", 100) _LOGGER.debug( "Service action [action_name] called with: %s=%s", ATTR_PARAMETER, parameter_value, ) # Get coordinator or API client from hass.data # For each config entry that this service action applies to: for entry_id, entry_data in hass.data[DOMAIN].items(): coordinator = entry_data # Or entry_data["coordinator"] try: # Perform the action action await coordinator.api_client.do_something(parameter_value) # Optionally refresh data await coordinator.async_request_refresh() except Exception as err: _LOGGER.error( "Error executing service action [action_name]: %s", err, ) # Consider raising HomeAssistantError for user visibility # Register the service action (legacy API uses hass.services) hass.services.async_register( # Legacy API: hass.services, not hass.actions DOMAIN, "[action_name]", async_handle_service_action, schema=SERVICE_SCHEMA, ) ``` **Option B: Entity-targeted service action** ```python async def async_handle_entity_service_action(entity, call: ServiceCall) -> None: """Handle service action call for specific entity.""" parameter_value = call.data[ATTR_PARAMETER] # Entity has access to coordinator await entity.coordinator.api_client.do_something( entity.device_id, parameter_value, ) await entity.coordinator.async_request_refresh() async def async_setup_service_action(hass: HomeAssistant) -> None: """Set up entity-targeted service action.""" platform = entity_platform.async_get_current_platform() platform.async_register_entity_service( # Note: uses 'service', not 'action' "[action_name]", SERVICE_SCHEMA, async_handle_entity_service_action, ) ``` ### 3. Register Service Action in `__init__.py` **File:** `custom_components/{domain}/__init__.py` **CRITICAL:** Service actions must register in `async_setup` or `setup`, NOT in `async_setup_entry`! Service actions are integration-wide, not per config entry. ```python from .service_actions.[action_name] import async_setup_service_action as async_setup_[action_name]_service_action async def async_setup(hass: HomeAssistant, config: dict) -> bool: """Set up the integration.""" # Register integration-wide service actions (only once for entire integration) await async_setup_[action_name]_service_action(hass) return True async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: """Set up from a config entry.""" # ... existing setup code ... # DO NOT register service actions here! return True ``` **For platform-specific service actions (entity service actions):** Register in platform `__init__.py` during `async_setup_entry`: ```python # In sensor/__init__.py or other platform from homeassistant.helpers import entity_platform async def async_setup_entry(...) -> None: """Set up platform.""" # ... add entities ... # Register entity service actions platform = entity_platform.async_get_current_platform() from ..service_actions.[action_name] import ( SERVICE_SCHEMA, async_handle_entity_service_action, ) platform.async_register_entity_service( # Uses 'service', not 'action' "[action_name]", SERVICE_SCHEMA, async_handle_entity_service_action, ) ``` ### 4. Add Service Action Constants **File:** `custom_components/{domain}/const.py` ```python # Service action names (use SERVICE_ prefix for legacy compatibility) SERVICE_[SERVICE_NAME] = "[action_name]" # Service action parameters ATTR_[PARAMETER_NAME] = "[parameter_name]" ``` ### 5. Add Translations **CRITICAL:** All action names, descriptions, and field labels MUST be in translation files under the `services` key. Per [HA documentation](https://developers.home-assistant.io/docs/internationalization/core#service-actions), `services.yaml` contains only the schema, not user-facing text. Note: The key is `services` (legacy) even though they are called "service actions" in documentation and "actions" in the UI. **`translations/en.json`:** ```json { "services": { "[action_name]": { "name": "[Action Name]", "description": "[Detailed description with **markdown** support. Can include [links](https://example.com) and formatting.]", "sections": { "basic": { "name": "Basic Settings", "description": "Essential parameters. You can use **markdown** here to highlight important information." }, "advanced": { "name": "Advanced Settings", "description": "Optional advanced configuration. See [documentation](https://example.com) for details." } }, "fields": { "[parameter_name]": { "name": "Parameter Name", "description": "Detailed explanation of what this parameter does. **Supports markdown**, can include ranges like `0-100`, examples, or [links](https://example.com)." }, "[another_parameter]": { "name": "Another Parameter", "description": "Another detailed description. Explain valid values, constraints, and behavior." }, "[advanced_parameter]": { "name": "Advanced Parameter", "description": "Advanced parameter description with technical details." } } } } } ``` **`translations/de.json`:** ```json { "services": { "[action_name]": { "name": "[German Action Name]", "description": "[Detaillierte Beschreibung mit **Markdown**-Unterstützung. Kann [Links](https://example.com) und Formatierung enthalten.]", "sections": { "basic": { "name": "Grundeinstellungen", "description": "Wesentliche Parameter. Sie können hier **Markdown** verwenden, um wichtige Informationen hervorzuheben." }, "advanced": { "name": "Erweiterte Einstellungen", "description": "Optionale erweiterte Konfiguration. Siehe [Dokumentation](https://example.com) für Details." } }, "fields": { "[parameter_name]": { "name": "Parametername", "description": "Detaillierte Erklärung, was dieser Parameter tut. **Unterstützt Markdown**, kann Bereiche wie `0-100`, Beispiele oder [Links](https://example.com) enthalten." }, "[another_parameter]": { "name": "Anderer Parameter", "description": "Eine weitere detaillierte Beschreibung. Erklären Sie gültige Werte, Einschränkungen und Verhalten." }, "[advanced_parameter]": { "name": "Erweiterter Parameter", "description": "Beschreibung des erweiterten Parameters mit technischen Details." } } } } } ``` **Translation structure:** - `services.[action_name].name` - Action display name (required) - `services.[action_name].description` - Action description (required) - `services.[action_name].sections.[section_key].name` - Section heading (if using sections) - `services.[action_name].sections.[section_key].description` - Section description (optional) - `services.[action_name].fields.[parameter_name].name` - Field label (required) - `services.[action_name].fields.[parameter_name].description` - Field description (required) **When `translation_key` is needed:** Only use `translation_key` in `services.yaml` for **select selectors** with dynamic options: ```json { "selector": { "fan_speed": { "options": { "off": "Off", "low": "Low", "medium": "Medium", "high": "High" } } } } ``` This maps to `selector: select: translation_key: "fan_speed"` in `services.yaml`. ### 6. Add Response Data (Optional) If service action returns data: ```python from homeassistant.core import SupportsResponse # In service action handler async def async_handle_service_action(call: ServiceCall) -> dict[str, Any]: """Handle service action and return data.""" result = await do_something() # Return response data return { "success": True, "value": result, } # When registering hass.services.async_register( # Legacy API: hass.services DOMAIN, "[action_name]", async_handle_service_action, schema=SERVICE_SCHEMA, supports_response=SupportsResponse.OPTIONAL, # OPTIONAL: may return data | ONLY: always returns data ) ``` **SupportsResponse values:** - `NONE` (default): Service action does not return data - `OPTIONAL`: Service action may conditionally return data - `ONLY`: Service action always returns data ### 7. Field Filtering by supported_features (Advanced) For entity actions with dynamic fields based on capabilities: ```yaml # In services.yaml [action_name]: target: entity: domain: fan fields: preset_mode: # Only show if entity has PRESET_MODE feature filter: supported_features: - fan.FanEntityFeature.PRESET_MODE selector: select: options: [] # Entity provides options dynamically ``` ### 8. Action Icons (2025 Best Practice) **CRITICAL:** Define icons for actions, sections, AND fields for better UX. **`icons.json`:** ```json { "actions": { "[action_name]": { "service": "mdi:icon-name", "sections": { "basic": "mdi:cog-outline", "advanced": "mdi:tune-vertical" } } } } ``` **Icon selection tips:** - Choose meaningful, recognizable icons from [Material Design Icons](https://pictogrammers.com/library/mdi/) - Actions: Use action-specific icons (e.g., `mdi:restart`, `mdi:update`, `mdi:cog-play`) - Sections: `mdi:cog-outline` (basic/general), `mdi:tune-vertical` (advanced/fine-tuning) - Fields: Consider in `services.yaml` if field needs visual distinction (e.g., `mdi:timer`, `mdi:thermometer`) ## Service Action Types ### Integration-Wide Service Action - Applies to all devices/entries - Example: Refresh all devices, reset cache ### Device-Targeted Service Action - Uses `target.device` selector - Applies to specific device - Example: Reboot device, update firmware ### Entity-Targeted Service Action - Uses `target.entity` selector - Applies to specific entity - Example: Set mode, calibrate sensor ## Validation Patterns ### Common Validators ```python import voluptuous as vol from homeassistant.helpers import config_validation as cv SERVICE_SCHEMA = vol.Schema({ vol.Required("string_param"): cv.string, vol.Required("int_param"): cv.positive_int, vol.Required("float_param"): vol.Range(min=0.0, max=100.0), vol.Required("bool_param"): cv.boolean, vol.Required("time_param"): cv.time, vol.Required("entity_id"): cv.entity_id, vol.Required("enum_param"): vol.In(["option1", "option2", "option3"]), vol.Optional("optional_param", default="default"): cv.string, }) ``` ### Custom Validator ```python def validate_custom(value: Any) -> Any: """Validate custom parameter.""" if not meets_criteria(value): raise vol.Invalid("Parameter does not meet criteria") return value SERVICE_SCHEMA = vol.Schema({ vol.Required("custom"): validate_custom, }) ``` ## Error Handling ```python from homeassistant.exceptions import HomeAssistantError async def async_handle_service_action(call: ServiceCall) -> None: """Handle service action with error handling.""" try: result = await do_something(call.data) except ConnectionError as err: raise HomeAssistantError( f"Failed to connect to device: {err}" ) from err except ValueError as err: raise HomeAssistantError( f"Invalid parameter value: {err}" ) from err ``` ## Validation Checklist - [ ] Service action defined in `services.yaml` with proper schema (no `name`/`description` fields!) - [ ] **CRITICAL:** NO static text in `services.yaml` - all user-facing text in translations under `services` key - [ ] `translation_key` only used for select selectors with dynamic options - [ ] Sections used for parameter organization (basic/advanced) if applicable - [ ] **Icons defined** in `icons.json` under `services` key for action, sections, and fields - [ ] **Descriptions provided** in translations under `services` key for action, sections, and fields - [ ] **Markdown used appropriately** - formatted descriptions where supported, plain text for names - [ ] Service action handler implemented with error handling - [ ] Service action registered in `async_setup` (integration-wide) using `hass.services.async_register()` - [ ] Entity service actions registered in platform using `platform.async_register_entity_service()` - [ ] **CRITICAL:** Integration service actions NOT registered in `async_setup_entry` - [ ] Constants added to `const.py` with `SERVICE_` prefix - [ ] Translations added (en, de) under `services` key with all required fields - [ ] SupportsResponse imported if service action returns data - [ ] Type hints complete (use `ServiceCall`, not `ActionCall`) - [ ] Docstrings added (refer to "service action" in comments) - [ ] `script/check` passes - [ ] Service action appears in HA Developer Tools > Actions tab - [ ] Service action UI shows icons and descriptions correctly - [ ] Service action executes correctly - [ ] Error cases handled appropriately ## Testing 1. Start H

{ "prompt": "# Add Service Action\n\nYour goal is to add a new **service action** to this Home Assistant integration that users can call from automations, scripts, or the UI.\n\n**Terminology:**\n\n- **Developer/Code:** \"service action\" (e.g., function names, comments, documentation)\n- **User-facing:** \"action\" only (e.g., in UI, translations under `actions` key)\n- **Legacy:** `services.yaml`, `hass.services.async_register()`, `ServiceCall` class (internal API)\n\nIf not provided, ask for:\n\n- Service action name and purpose\n- Parameters required (with types and validation)\n- What the service action does (API call, state change, etc.)\n- Response data (if any)\n- Target: device, entity, or integration-wide\n\n## Implementation Steps\n\n### 1. Define Service Action in `services.yaml`\n\n**File:** `custom_components/{domain}/services.yaml`\n\n**Note:** `services.yaml` is a legacy filename from when these were called \"services\". We now call them \"service actions\" in code and \"actions\" for users.\n\n**CRITICAL:** Per [HA documentation](https://developers.home-assistant.io/docs/dev_101_services), action names and descriptions must be defined in translation files under the `actions` key (not `services`), NOT in `services.yaml`. The `services.yaml` file only defines the schema.\n\nAdd service action definition:\n\n```yaml\n[action_name]:\n # Use translation_key to reference translations\n translation_key: [action_name]\n\n # For device or entity-targeted service actions\n target:\n entity:\n domain: [platform] # sensor, switch, etc.\n # OR\n integration: { domain }\n\n # Service action parameters - organize with sections for better UX\n fields:\n # SECTION: Basic parameters\n [parameter_name]:\n translation_key: [parameter_name]\n required: true\n example: \"[example value]\"\n selector:\n text:\n # OR number:, boolean:, select:, etc.\n\n [another_parameter]:\n translation_key: [another_parameter]\n required: false\n default: [default value]\n selector:\n number:\n min: 0\n max: 100\n mode: slider\n\n # Advanced section (appears collapsed by default)\n advanced:\n collapsed: true\n fields:\n [advanced_parameter]:\n translation_key: [advanced_parameter]\n required: false\n selector:\n boolean:\n```\n\n**With sections for better organization:**\n\n```yaml\n[action_name]:\n # No name/description - translations only!\n\n target:\n entity:\n integration: { domain }\n\n fields:\n # Basic section - always visible\n basic:\n # Section names come from translations: actions.[action_name].sections.basic.name\n collapsed: false\n icon: mdi:cog-outline\n fields:\n [parameter_name]:\n # Field names come from translations: actions.[action_name].fields.[parameter_name].name\n required: true\n selector:\n text:\n\n # Advanced section - collapsed by default\n advanced:\n # Section names come from translations: actions.[action_name].sections.advanced.name\n collapsed: true\n icon: mdi:tune-vertical\n fields:\n [advanced_parameter]:\n # Field names come from translations: actions.[action_name].fields.[advanced_parameter].name\n required: false\n selector:\n boolean:\n```\n\n**Special case: `translation_key` in selectors**\n\nUse `translation_key` only for `select` selectors with dynamic options:\n\n```yaml\nfields:\n preset_mode:\n selector:\n select:\n translation_key: \"fan_speed\" # Only needed here!\n options:\n - \"off\"\n - \"low\"\n - \"medium\"\n - \"high\"\n```\n\nThis allows translating the option labels via `selector.[translation_key].options.[option_value]` in translations.\n\n**Best Practices for Schema Definition:**\n\n1. **Always add icons** - Provide meaningful icons for sections AND individual fields where applicable\n - Sections: `icon: mdi:cog-outline` (basic), `icon: mdi:tune-vertical` (advanced)\n - Fields: Consider field type and purpose (e.g., `mdi:timer` for duration, `mdi:thermometer` for temperature)\n\n2. **Always add descriptions** - Provide descriptions wherever the schema allows (sections, fields)\n - Makes the UI more user-friendly\n - Helps users understand what each parameter does\n\n3. **Markdown support** - Be aware of where markdown is supported:\n - ✅ **Service action descriptions** - Markdown is supported\n - ✅ **Section descriptions** - Markdown is supported\n - ❌ **Field names** - Plain text only (keep short, 2-4 words)\n - ✅ **Field descriptions** - Markdown is supported (can use `**bold**`, `[links](url)`, etc.)\n - Use markdown for formatting longer descriptions, links to documentation, etc.\n\n4. **Choose text appropriately**:\n - Names: Short, concise labels (2-4 words)\n - Descriptions: Detailed explanations with examples, constraints, or links\n - Use field descriptions to explain valid ranges, formats, or special behavior\n\n**Reference:** [Home Assistant Services Documentation](https://developers.home-assistant.io/docs/dev_101_services)\n\n### 2. Create Service Action Handler\n\n**Directory naming:** Use `service_actions/` for new code (preferred) or `actions/` (acceptable). Be consistent within your integration.\n\n**Option A: Simple service action in `service_actions/` directory**\n\nCreate `custom_components/{domain}/service_actions/[action_name].py`:\n\n```python\n\"\"\"[Action name] service action for [Integration Title].\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom typing import Any\n\nimport voluptuous as vol\n\nfrom homeassistant.core import HomeAssistant, ServiceCall, SupportsResponse\nfrom homeassistant.helpers import config_validation as cv\n\nfrom ..const import DOMAIN\n\n_LOGGER = logging.getLogger(__name__)\n\n# Action parameter constants\nATTR_PARAMETER = \"parameter_name\"\n\n# Action schema for validation\nSERVICE_SCHEMA = vol.Schema(\n {\n vol.Required(ATTR_PARAMETER): cv.string,\n # Add more parameters with validators\n vol.Optional(\"optional_param\", default=100): cv.positive_int,\n }\n)\n\n\nasync def async_setup_service_action(hass: HomeAssistant) -> None:\n \"\"\"Set up the [action_name] service action.\"\"\"\n\n async def async_handle_service_action(call: ServiceCall) -> None:\n \"\"\"Handle the service action call.\"\"\"\n # Extract parameters\n parameter_value = call.data[ATTR_PARAMETER]\n optional_value = call.data.get(\"optional_param\", 100)\n\n _LOGGER.debug(\n \"Service action [action_name] called with: %s=%s\",\n ATTR_PARAMETER,\n parameter_value,\n )\n\n # Get coordinator or API client from hass.data\n # For each config entry that this service action applies to:\n for entry_id, entry_data in hass.data[DOMAIN].items():\n coordinator = entry_data # Or entry_data[\"coordinator\"]\n\n try:\n # Perform the action action\n await coordinator.api_client.do_something(parameter_value)\n\n # Optionally refresh data\n await coordinator.async_request_refresh()\n\n except Exception as err:\n _LOGGER.error(\n \"Error executing service action [action_name]: %s\",\n err,\n )\n # Consider raising HomeAssistantError for user visibility\n\n # Register the service action (legacy API uses hass.services)\n hass.services.async_register( # Legacy API: hass.services, not hass.actions\n DOMAIN,\n \"[action_name]\",\n async_handle_service_action,\n schema=SERVICE_SCHEMA,\n )\n```\n\n**Option B: Entity-targeted service action**\n\n```python\nasync def async_handle_entity_service_action(entity, call: ServiceCall) -> None:\n \"\"\"Handle service action call for specific entity.\"\"\"\n parameter_value = call.data[ATTR_PARAMETER]\n\n # Entity has access to coordinator\n await entity.coordinator.api_client.do_something(\n entity.device_id,\n parameter_value,\n )\n await entity.coordinator.async_request_refresh()\n\n\nasync def async_setup_service_action(hass: HomeAssistant) -> None:\n \"\"\"Set up entity-targeted service action.\"\"\"\n platform = entity_platform.async_get_current_platform()\n\n platform.async_register_entity_service( # Note: uses 'service', not 'action'\n \"[action_name]\",\n SERVICE_SCHEMA,\n async_handle_entity_service_action,\n )\n```\n\n### 3. Register Service Action in `__init__.py`\n\n**File:** `custom_components/{domain}/__init__.py`\n\n**CRITICAL:** Service actions must register in `async_setup` or `setup`, NOT in `async_setup_entry`!\n\nService actions are integration-wide, not per config entry.\n\n```python\nfrom .service_actions.[action_name] import async_setup_service_action as async_setup_[action_name]_service_action\n\nasync def async_setup(hass: HomeAssistant, config: dict) -> bool:\n \"\"\"Set up the integration.\"\"\"\n # Register integration-wide service actions (only once for entire integration)\n await async_setup_[action_name]_service_action(hass)\n\n return True\n\n\nasync def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:\n \"\"\"Set up from a config entry.\"\"\"\n # ... existing setup code ...\n # DO NOT register service actions here!\n\n return True\n```\n\n**For platform-specific service actions (entity service actions):**\n\nRegister in platform `__init__.py` during `async_setup_entry`:\n\n```python\n# In sensor/__init__.py or other platform\nfrom homeassistant.helpers import entity_platform\n\nasync def async_setup_entry(...) -> None:\n \"\"\"Set up platform.\"\"\"\n # ... add entities ...\n\n # Register entity service actions\n platform = entity_platform.async_get_current_platform()\n\n from ..service_actions.[action_name] import (\n SERVICE_SCHEMA,\n async_handle_entity_service_action,\n )\n\n platform.async_register_entity_service( # Uses 'service', not 'action'\n \"[action_name]\",\n SERVICE_SCHEMA,\n async_handle_entity_service_action,\n )\n```\n\n### 4. Add Service Action Constants\n\n**File:** `custom_components/{domain}/const.py`\n\n```python\n# Service action names (use SERVICE_ prefix for legacy compatibility)\nSERVICE_[SERVICE_NAME] = \"[action_name]\"\n\n# Service action parameters\nATTR_[PARAMETER_NAME] = \"[parameter_name]\"\n```\n\n### 5. Add Translations\n\n**CRITICAL:** All action names, descriptions, and field labels MUST be in translation files under the `services` key. Per [HA documentation](https://developers.home-assistant.io/docs/internationalization/core#service-actions), `services.yaml` contains only the schema, not user-facing text. Note: The key is `services` (legacy) even though they are called \"service actions\" in documentation and \"actions\" in the UI.\n\n**`translations/en.json`:**\n\n```json\n{\n \"services\": {\n \"[action_name]\": {\n \"name\": \"[Action Name]\",\n \"description\": \"[Detailed description with **markdown** support. Can include [links](https://example.com) and formatting.]\",\n \"sections\": {\n \"basic\": {\n \"name\": \"Basic Settings\",\n \"description\": \"Essential parameters. You can use **markdown** here to highlight important information.\"\n },\n \"advanced\": {\n \"name\": \"Advanced Settings\",\n \"description\": \"Optional advanced configuration. See [documentation](https://example.com) for details.\"\n }\n },\n \"fields\": {\n \"[parameter_name]\": {\n \"name\": \"Parameter Name\",\n \"description\": \"Detailed explanation of what this parameter does. **Supports markdown**, can include ranges like `0-100`, examples, or [links](https://example.com).\"\n },\n \"[another_parameter]\": {\n \"name\": \"Another Parameter\",\n \"description\": \"Another detailed description. Explain valid values, constraints, and behavior.\"\n },\n \"[advanced_parameter]\": {\n \"name\": \"Advanced Parameter\",\n \"description\": \"Advanced parameter description with technical details.\"\n }\n }\n }\n }\n}\n```\n\n**`translations/de.json`:**\n\n```json\n{\n \"services\": {\n \"[action_name]\": {\n \"name\": \"[German Action Name]\",\n \"description\": \"[Detaillierte Beschreibung mit **Markdown**-Unterstützung. Kann [Links](https://example.com) und Formatierung enthalten.]\",\n \"sections\": {\n \"basic\": {\n \"name\": \"Grundeinstellungen\",\n \"description\": \"Wesentliche Parameter. Sie können hier **Markdown** verwenden, um wichtige Informationen hervorzuheben.\"\n },\n \"advanced\": {\n \"name\": \"Erweiterte Einstellungen\",\n \"description\": \"Optionale erweiterte Konfiguration. Siehe [Dokumentation](https://example.com) für Details.\"\n }\n },\n \"fields\": {\n \"[parameter_name]\": {\n \"name\": \"Parametername\",\n \"description\": \"Detaillierte Erklärung, was dieser Parameter tut. **Unterstützt Markdown**, kann Bereiche wie `0-100`, Beispiele oder [Links](https://example.com) enthalten.\"\n },\n \"[another_parameter]\": {\n \"name\": \"Anderer Parameter\",\n \"description\": \"Eine weitere detaillierte Beschreibung. Erklären Sie gültige Werte, Einschränkungen und Verhalten.\"\n },\n \"[advanced_parameter]\": {\n \"name\": \"Erweiterter Parameter\",\n \"description\": \"Beschreibung des erweiterten Parameters mit technischen Details.\"\n }\n }\n }\n }\n}\n```\n\n**Translation structure:**\n\n- `services.[action_name].name` - Action display name (required)\n- `services.[action_name].description` - Action description (required)\n- `services.[action_name].sections.[section_key].name` - Section heading (if using sections)\n- `services.[action_name].sections.[section_key].description` - Section description (optional)\n- `services.[action_name].fields.[parameter_name].name` - Field label (required)\n- `services.[action_name].fields.[parameter_name].description` - Field description (required)\n\n**When `translation_key` is needed:**\n\nOnly use `translation_key` in `services.yaml` for **select selectors** with dynamic options:\n\n```json\n{\n \"selector\": {\n \"fan_speed\": {\n \"options\": {\n \"off\": \"Off\",\n \"low\": \"Low\",\n \"medium\": \"Medium\",\n \"high\": \"High\"\n }\n }\n }\n}\n```\n\nThis maps to `selector: select: translation_key: \"fan_speed\"` in `services.yaml`.\n\n### 6. Add Response Data (Optional)\n\nIf service action returns data:\n\n```python\nfrom homeassistant.core import SupportsResponse\n\n# In service action handler\nasync def async_handle_service_action(call: ServiceCall) -> dict[str, Any]:\n \"\"\"Handle service action and return data.\"\"\"\n result = await do_something()\n\n # Return response data\n return {\n \"success\": True,\n \"value\": result,\n }\n\n# When registering\nhass.services.async_register( # Legacy API: hass.services\n DOMAIN,\n \"[action_name]\",\n async_handle_service_action,\n schema=SERVICE_SCHEMA,\n supports_response=SupportsResponse.OPTIONAL, # OPTIONAL: may return data | ONLY: always returns data\n)\n```\n\n**SupportsResponse values:**\n\n- `NONE` (default): Service action does not return data\n- `OPTIONAL`: Service action may conditionally return data\n- `ONLY`: Service action always returns data\n\n### 7. Field Filtering by supported_features (Advanced)\n\nFor entity actions with dynamic fields based on capabilities:\n\n```yaml\n# In services.yaml\n[action_name]:\n target:\n entity:\n domain: fan\n fields:\n preset_mode:\n # Only show if entity has PRESET_MODE feature\n filter:\n supported_features:\n - fan.FanEntityFeature.PRESET_MODE\n selector:\n select:\n options: [] # Entity provides options dynamically\n```\n\n### 8. Action Icons (2025 Best Practice)\n\n**CRITICAL:** Define icons for actions, sections, AND fields for better UX.\n\n**`icons.json`:**\n\n```json\n{\n \"actions\": {\n \"[action_name]\": {\n \"service\": \"mdi:icon-name\",\n \"sections\": {\n \"basic\": \"mdi:cog-outline\",\n \"advanced\": \"mdi:tune-vertical\"\n }\n }\n }\n}\n```\n\n**Icon selection tips:**\n\n- Choose meaningful, recognizable icons from [Material Design Icons](https://pictogrammers.com/library/mdi/)\n- Actions: Use action-specific icons (e.g., `mdi:restart`, `mdi:update`, `mdi:cog-play`)\n- Sections: `mdi:cog-outline` (basic/general), `mdi:tune-vertical` (advanced/fine-tuning)\n- Fields: Consider in `services.yaml` if field needs visual distinction (e.g., `mdi:timer`, `mdi:thermometer`)\n\n## Service Action Types\n\n### Integration-Wide Service Action\n\n- Applies to all devices/entries\n- Example: Refresh all devices, reset cache\n\n### Device-Targeted Service Action\n\n- Uses `target.device` selector\n- Applies to specific device\n- Example: Reboot device, update firmware\n\n### Entity-Targeted Service Action\n\n- Uses `target.entity` selector\n- Applies to specific entity\n- Example: Set mode, calibrate sensor\n\n## Validation Patterns\n\n### Common Validators\n\n```python\nimport voluptuous as vol\nfrom homeassistant.helpers import config_validation as cv\n\nSERVICE_SCHEMA = vol.Schema({\n vol.Required(\"string_param\"): cv.string,\n vol.Required(\"int_param\"): cv.positive_int,\n vol.Required(\"float_param\"): vol.Range(min=0.0, max=100.0),\n vol.Required(\"bool_param\"): cv.boolean,\n vol.Required(\"time_param\"): cv.time,\n vol.Required(\"entity_id\"): cv.entity_id,\n vol.Required(\"enum_param\"): vol.In([\"option1\", \"option2\", \"option3\"]),\n vol.Optional(\"optional_param\", default=\"default\"): cv.string,\n})\n```\n\n### Custom Validator\n\n```python\ndef validate_custom(value: Any) -> Any:\n \"\"\"Validate custom parameter.\"\"\"\n if not meets_criteria(value):\n raise vol.Invalid(\"Parameter does not meet criteria\")\n return value\n\nSERVICE_SCHEMA = vol.Schema({\n vol.Required(\"custom\"): validate_custom,\n})\n```\n\n## Error Handling\n\n```python\nfrom homeassistant.exceptions import HomeAssistantError\n\nasync def async_handle_service_action(call: ServiceCall) -> None:\n \"\"\"Handle service action with error handling.\"\"\"\n try:\n result = await do_something(call.data)\n\n except ConnectionError as err:\n raise HomeAssistantError(\n f\"Failed to connect to device: {err}\"\n ) from err\n\n except ValueError as err:\n raise HomeAssistantError(\n f\"Invalid parameter value: {err}\"\n ) from err\n```\n\n## Validation Checklist\n\n- [ ] Service action defined in `services.yaml` with proper schema (no `name`/`description` fields!)\n- [ ] **CRITICAL:** NO static text in `services.yaml` - all user-facing text in translations under `services` key\n- [ ] `translation_key` only used for select selectors with dynamic options\n- [ ] Sections used for parameter organization (basic/advanced) if applicable\n- [ ] **Icons defined** in `icons.json` under `services` key for action, sections, and fields\n- [ ] **Descriptions provided** in translations under `services` key for action, sections, and fields\n- [ ] **Markdown used appropriately** - formatted descriptions where supported, plain text for names\n- [ ] Service action handler implemented with error handling\n- [ ] Service action registered in `async_setup` (integration-wide) using `hass.services.async_register()`\n- [ ] Entity service actions registered in platform using `platform.async_register_entity_service()`\n- [ ] **CRITICAL:** Integration service actions NOT registered in `async_setup_entry`\n- [ ] Constants added to `const.py` with `SERVICE_` prefix\n- [ ] Translations added (en, de) under `services` key with all required fields\n- [ ] SupportsResponse imported if service action returns data\n- [ ] Type hints complete (use `ServiceCall`, not `ActionCall`)\n- [ ] Docstrings added (refer to \"service action\" in comments)\n- [ ] `script/check` passes\n- [ ] Service action appears in HA Developer Tools > Actions tab\n- [ ] Service action UI shows icons and descriptions correctly\n- [ ] Service action executes correctly\n- [ ] Error cases handled appropriately\n\n## Testing\n\n1. Start H", "variables": [], "notes": "Add a new service action to the integration with proper schema and registration Tools: search/codebase, edit, search.", "metadata": { "source": { "provider": "github-prompts", "repository": "https://github.com/pantherale0/ha-hellofresh", "path": ".github/prompts/Add Action.prompt.md", "ref": "311b33b535db59c37269a47af66f4ec711abdb9d", "url": "https://github.com/pantherale0/ha-hellofresh/blob/311b33b535db59c37269a47af66f4ec711abdb9d/.github/prompts/Add Action.prompt.md", "key": "pantherale0/ha-hellofresh/.github/prompts/Add Action.prompt.md" } } }

Add Action

About

Add Service Action

Implementation Steps

1. Define Service Action in `services.yaml`

2. Create Service Action Handler

3. Register Service Action in `init.py`

4. Add Service Action Constants

5. Add Translations

6. Add Response Data (Optional)

7. Field Filtering by supported_features (Advanced)

8. Action Icons (2025 Best Practice)

Service Action Types

Integration-Wide Service Action

Device-Targeted Service Action

Entity-Targeted Service Action

Validation Patterns

Common Validators

Custom Validator

Error Handling

Validation Checklist

Testing

Additional Resources

Integration Context

Output

Use it

Manifest

Reviews

About

Add Service Action

Implementation Steps

1. Define Service Action in services.yaml

2. Create Service Action Handler

3. Register Service Action in __init__.py

4. Add Service Action Constants

5. Add Translations

6. Add Response Data (Optional)

7. Field Filtering by supported_features (Advanced)

8. Action Icons (2025 Best Practice)

Service Action Types

Integration-Wide Service Action

Device-Targeted Service Action

Entity-Targeted Service Action

Validation Patterns

Common Validators

Custom Validator

Error Handling

Validation Checklist

Testing

Additional Resources

Integration Context

Output

Use it

Manifest

Reviews

1. Define Service Action in `services.yaml`

3. Register Service Action in `init.py`