> ## 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.
# Native Functions
> Built-in functions provided by Extended OpenAI Conversation
Native functions are built-in capabilities provided directly by the Extended OpenAI Conversation component. These functions are implemented in Python and offer core functionality.
## Available Native Functions
### execute\_service
Call any Home Assistant service with specified parameters.
The domain of the service (e.g., `light`, `switch`, `climate`)
The service to call (e.g., `turn_on`, `turn_off`, `set_temperature`)
Service data object with the following properties:
* `entity_id` (string): Target entity ID
* `device_id` (string): Target device ID (optional)
* `area_id` (string): Target area ID (optional)
Control Home Assistant devices and services:
```yaml theme={null}
- spec:
name: execute_services
description: Use this function to execute service of devices in Home Assistant.
parameters:
type: object
properties:
list:
type: array
items:
type: object
properties:
domain:
type: string
description: The domain of the service
service:
type: string
description: The service to be called
service_data:
type: object
description: The service data object to indicate what to control.
properties:
entity_id:
type: string
description: The entity_id retrieved from available devices. It must start with domain, followed by dot character.
required:
- entity_id
required:
- domain
- service
- service_data
function:
type: native
name: execute_service
```
### add\_automation
Create Home Assistant automations dynamically through conversation.
Before using this function, set up notifications for the `automation_registered_via_extended_openai_conversation` event. Automations can be created even if the conversation fails to get a response.
Automation configuration in valid YAML format. Newline characters should be `\n`.
1. **Create a separate assistant** for automation creation to avoid accidental automation registration
2. **Set up event notifications** to monitor created automations
3. **Review automations** before enabling them in production
**Create Separate Assistant**
**Notify on Created**
**English Configuration:**
```yaml theme={null}
- spec:
name: add_automation
description: Use this function to add an automation in Home Assistant.
parameters:
type: object
properties:
automation_config:
type: string
description: A configuration for automation in a valid yaml format. Next line character should be \n. Use devices from the list.
required:
- automation_config
function:
type: native
name: add_automation
```
**Korean Configuration:**
For Korean language, use `\\n` instead of `\n` for newline characters:
```yaml theme={null}
- spec:
name: add_automation
description: Use this function to add an automation in Home Assistant.
parameters:
type: object
properties:
automation_config:
type: string
description: A configuration for automation in a valid yaml format. Next line character should be \\n, not \n. Use devices from the list.
required:
- automation_config
function:
type: native
name: add_automation
```
### get\_history
Retrieve historical state data for specified entities.
List of entity IDs to retrieve history for
Start of the history period in `%Y-%m-%dT%H:%M:%S%z` format. Defaults to 1 day before the request time.
End of the history period in `%Y-%m-%dT%H:%M:%S%z` format. Defaults to current time.
Only return `last_changed` and `state` for non-first/last states. Default: `true`
Skip returning attributes from the database. Default: `true`
Only return significant state changes. Default: `true`
Retrieve historical state data for entities. For advanced formatting with templates, see the [composite function example](/functions/composite#example-get-history-with-formatting).
```yaml theme={null}
- spec:
name: get_history
description: Retrieve historical data of specified entities.
parameters:
type: object
properties:
entity_ids:
type: array
items:
type: string
description: The entity id to filter.
start_time:
type: string
description: Start of the history period in "%Y-%m-%dT%H:%M:%S%z".
end_time:
type: string
description: End of the history period in "%Y-%m-%dT%H:%M:%S%z".
minimal_response:
type: boolean
description: Only return last_changed and state for non-first/last states.
no_attributes:
type: boolean
description: Skip returning attributes from the database.
significant_changes_only:
type: boolean
description: Only return significant state changes.
required:
- entity_ids
function:
type: native
name: get_history
```
### get\_energy
Retrieve energy configuration and preferences from Home Assistant's energy management system.
This function returns the energy dashboard configuration including solar, grid, battery, and gas sources. No parameters required.
Retrieve energy management configuration:
```yaml theme={null}
- spec:
name: get_energy
description: Retrieve energy management configuration and preferences.
parameters:
type: object
properties: {}
function:
type: native
name: get_energy
```
### get\_statistics
Retrieve statistical data for specified entities over a time period.
List of statistic IDs to retrieve data for
Start of the statistics period in `%Y-%m-%dT%H:%M:%S%z` format
End of the statistics period in `%Y-%m-%dT%H:%M:%S%z` format
Aggregation period. Options: `5minute`, `hour`, `day`, `month`. Default: `day`
Unit conversion configuration (optional)
Types of statistics to return. Default: `["change"]`
Retrieve statistical data for energy consumption or other long-term statistics:
```yaml theme={null}
- spec:
name: get_statistics
description: Retrieve statistical data for specified entities over a time period.
parameters:
type: object
properties:
statistic_ids:
type: array
items:
type: string
description: The statistic id to retrieve data for.
start_time:
type: string
description: Start of the statistics period in "%Y-%m-%dT%H:%M:%S%z".
end_time:
type: string
description: End of the statistics period in "%Y-%m-%dT%H:%M:%S%z".
period:
type: string
description: Aggregation period (5minute, hour, day, month).
types:
type: array
items:
type: string
description: Types of statistics to return.
required:
- start_time
- end_time
function:
type: native
name: get_statistics
```
## Use Cases
Use `execute_service` to control lights, switches, and other devices
Use `add_automation` to create automations through conversation
Use `get_history` to analyze entity state changes over time
Use `get_energy` to retrieve energy dashboard configuration
Use `get_statistics` for long-term statistical data and trends
Combine functions to create monitoring and notification workflows
## Next Steps
Dynamic templates
Service sequences
Chain functions
