Script Functions

Execute sequences of Home Assistant services

Script functions execute sequences of Home Assistant services, similar to Home Assistant scripts. They’re perfect for multi-step actions or calling services with specific data.

Configuration

function:
  type: script
  sequence:
    - service: domain.service_name
      data:
        param: "{{ value }}"

sequence · array · required

List of service calls to execute in order

Basic Examples

Add Item to Shopping Cart

- spec:
    name: add_item_to_shopping_cart
    description: Add item to shopping cart
    parameters:
      type: object
      properties:
        item:
          type: string
          description: The item to be added to cart
      required:
      - item
  function:
    type: script
    sequence:
    - service: shopping_list.add_item
      data:
        name: '{{item}}'

Send Notification

- spec:
    name: send_message_to_line
    description: Use this function to send message to Line.
    parameters:
      type: object
      properties:
        message:
          type: string
          description: message you want to send
      required:
      - message
  function:
    type: script
    sequence:
    - service: script.notify_all
      data:
        message: "{{ message }}"

Advanced Examples

Get Calendar Events

Use response_variable to pass service results back to the AI:

- spec:
    name: get_events
    description: Use this function to get list of calendar events.
    parameters:
      type: object
      properties:
        start_date_time:
          type: string
          description: The start date time in '%Y-%m-%dT%H:%M:%S%z' format
        end_date_time:
          type: string
          description: The end date time in '%Y-%m-%dT%H:%M:%S%z' format
      required:
      - start_date_time
      - end_date_time
  function:
    type: script
    sequence:
    - service: calendar.get_events
      data:
        start_date_time: "{{start_date_time}}"
        end_date_time: "{{end_date_time}}"
      target:
        entity_id:
        - calendar.personal
        - calendar.work
      response_variable: _function_result

Set response_variable: _function_result to return the service response to the AI.

Play YouTube on TV

Chain multiple service calls with delays:

- spec:
    name: play_youtube
    description: Use this function to play Youtube.
    parameters:
      type: object
      properties:
        video_id:
          type: string
          description: The video id.
      required:
      - video_id
  function:
    type: script
    sequence:
    - service: webostv.command
      data:
        entity_id: media_player.living_room_tv
        command: system.launcher/launch
        payload:
          id: youtube.leanback.v4
          contentId: "{{video_id}}"
    - delay:
        seconds: 10
    - service: webostv.button
      data:
        entity_id: media_player.living_room_tv
        button: ENTER

Play Netflix on TV

- spec:
    name: play_netflix
    description: Use this function to play Netflix.
    parameters:
      type: object
      properties:
        video_id:
          type: string
          description: The video id.
      required:
      - video_id
  function:
    type: script
    sequence:
    - service: webostv.command
      data:
        entity_id: media_player.living_room_tv
        command: system.launcher/launch
        payload:
          id: netflix
          contentId: "m=https://www.netflix.com/watch/{{video_id}}"

Get Weather Forecasts

- spec:
    name: get_weather_forecasts
    description: Get hourly and daily weather forecasts
    parameters:
      type: object
      properties:
        entity_id:
          type: string
          description: Weather entity to query
        type:
          type: string
          enum: ["daily", "hourly"]
          description: Forecast type
      required:
      - entity_id
      - type
  function:
    type: script
    sequence:
      - service: weather.get_forecasts
        data:
          type: "{{ type }}"
        target:
          entity_id: "{{ entity_id }}"
        response_variable: _function_result

Script Features

Service Targeting

Target entities, devices, or areas:

sequence:
  - service: light.turn_on
    target:
      entity_id: light.bedroom
      # OR
      device_id: abc123
      # OR
      area_id: bedroom

Delays

Add delays between service calls:

sequence:
  - service: light.turn_on
    target:
      entity_id: light.bedroom
  - delay:
      hours: 0
      minutes: 5
      seconds: 30
  - service: light.turn_off
    target:
      entity_id: light.bedroom

Response Variables

Capture service responses:

sequence:
  - service: weather.get_forecasts
    data:
      type: daily
    target:
      entity_id: weather.home
    response_variable: _function_result

The response is passed back to the AI as the function result.

Templates in Data

Use Jinja2 templates in service data:

sequence:
  - service: notify.mobile_app
    data:
      message: "Temperature is {{ states('sensor.temperature') }}°C"
      title: "{{ message_title }}"

Use Cases

Multi-step Actions

Execute sequences of services in order

Data Retrieval

Call services and return responses to AI

Media Control

Control media players with complex payloads

Notifications

Send messages through various notification services

Best Practices

1. Use response_variable for data

   When you need the AI to process service results, always set response_variable: _function_result

2. Add delays when needed

   Some devices need time to process commands. Add appropriate delays between service calls.

3. Target correctly

   Use the most appropriate targeting method:

   • entity_id for specific entities
   • device_id for all entities of a device
   • area_id for all entities in an area
4. Keep sequences focused

   Each function should accomplish one logical task. For complex workflows, use composite functions.

Next Steps

REST Functions

Fetch external data

Composite Functions

Chain multiple functions

Script Integration

Home Assistant scripts