> ## Documentation Index
> Fetch the complete documentation index at: https://extended-openai-conversation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Script Functions

> Execute sequences of Home Assistant services

Script functions execute sequences of Home Assistant services, similar to [Home Assistant scripts](https://www.home-assistant.io/integrations/script/). They're perfect for multi-step actions or calling services with specific data.

## Configuration

```yaml theme={null}
function:
  type: script
  sequence:
    - service: domain.service_name
      data:
        param: "{{ value }}"
```

<ParamField path="sequence" type="array" required>
  List of service calls to execute in order
</ParamField>

## Basic Examples

### Add Item to Shopping Cart

```yaml theme={null}
- 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}}'
```

<Frame>
  <img width="300" alt="Shopping List" src="https://github.com/jekalmin/extended_openai_conversation/assets/2917984/89060728-4703-4e57-8423-354cdc47f0ee" />
</Frame>

### Send Notification

```yaml theme={null}
- 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 }}"
```

<Frame>
  <img width="300" alt="Notification" src="https://github.com/jekalmin/extended_openai_conversation/assets/2917984/16dc4ca0-c823-4dfe-a2b7-1ba7623acc70" />
</Frame>

## Advanced Examples

### Get Calendar Events

Use `response_variable` to pass service results back to the AI:

```yaml theme={null}
- 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
```

<Frame>
  <img width="300" alt="Calendar Events" src="https://github.com/jekalmin/extended_openai_conversation/assets/2917984/7a6c6925-a53e-4363-a93c-45f63951d41b" />
</Frame>

<Note>
  Set `response_variable: _function_result` to return the service response to the AI.
</Note>

### Play YouTube on TV

Chain multiple service calls with delays:

```yaml theme={null}
- 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
```

<Frame>
  <img width="300" alt="YouTube" src="https://github.com/jekalmin/extended_openai_conversation/assets/2917984/d5c9e0db-8d7c-4a7a-bc46-b043627ffec6" />
</Frame>

### Play Netflix on TV

```yaml theme={null}
- 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}}"
```

<Frame>
  <img width="300" alt="Netflix" src="https://github.com/jekalmin/extended_openai_conversation/assets/2917984/346065d3-7ab9-49c8-ba30-b79b37a5f084" />
</Frame>

### Get Weather Forecasts

```yaml theme={null}
- 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

<AccordionGroup>
  <Accordion title="Service Targeting">
    Target entities, devices, or areas:

    ```yaml theme={null}
    sequence:
      - service: light.turn_on
        target:
          entity_id: light.bedroom
          # OR
          device_id: abc123
          # OR
          area_id: bedroom
    ```
  </Accordion>

  <Accordion title="Delays">
    Add delays between service calls:

    ```yaml theme={null}
    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
    ```
  </Accordion>

  <Accordion title="Response Variables">
    Capture service responses:

    ```yaml theme={null}
    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.
  </Accordion>

  <Accordion title="Templates in Data">
    Use Jinja2 templates in service data:

    ```yaml theme={null}
    sequence:
      - service: notify.mobile_app
        data:
          message: "Temperature is {{ states('sensor.temperature') }}°C"
          title: "{{ message_title }}"
    ```
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Multi-step Actions" icon="list-check">
    Execute sequences of services in order
  </Card>

  <Card title="Data Retrieval" icon="download">
    Call services and return responses to AI
  </Card>

  <Card title="Media Control" icon="tv">
    Control media players with complex payloads
  </Card>

  <Card title="Notifications" icon="bell">
    Send messages through various notification services
  </Card>
</CardGroup>

## Best Practices

<Steps>
  <Step title="Use response_variable for data">
    When you need the AI to process service results, always set `response_variable: _function_result`
  </Step>

  <Step title="Add delays when needed">
    Some devices need time to process commands. Add appropriate delays between service calls.
  </Step>

  <Step title="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
  </Step>

  <Step title="Keep sequences focused">
    Each function should accomplish one logical task. For complex workflows, use composite functions.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={3}>
  <Card title="REST Functions" icon="globe" href="/functions/rest">
    Fetch external data
  </Card>

  <Card title="Composite Functions" icon="layer-group" href="/functions/composite">
    Chain multiple functions
  </Card>

  <Card title="Script Integration" icon="book" href="https://www.home-assistant.io/integrations/script/">
    Home Assistant scripts
  </Card>
</CardGroup>