home-assistant.io/source/_integrations/conversation.markdown

title	description	ha_category	ha_release	ha_quality_scale	ha_codeowners	ha_domain	ha_integration_type
Conversation	Instructions on how to have conversations with your Home Assistant.	Voice	0.7	internal	@home-assistant/core @synesthesiam	conversation	system

The Conversation {% term integration %} allows you to converse with Home Assistant. You can either converse by pressing the microphone in the frontend (supported browsers only (no iOS)) or by calling the conversation/process action with the transcribed text.

Screenshot of the conversation interface in Home Assistant.

# Example base configuration.yaml entry
conversation:

Default sentences

By default, a collection of community contributed sentences are supported in a growing list of languages.

In English, you can say things like "turn on kitchen lights" or "turn off lights in the bedroom" if you have an area named "bedroom".

Adding custom sentences

You can add your own sentence templates to teach Home Assistant about new sentences. These sentences can work with the built-in intents or trigger a custom action by defining custom {% term intents %} with the intent script integration.

To get started, create a custom_sentences/<language> directory in your Home Assistant config directory where <language> is the language code of your language, such as en for English. These YAML files are automatically merged, and may contain intents, lists, or expansion rules.

For an English example, create the file config/custom_sentences/en/temperature.yaml and add:

{% raw %}

# Example temperature.yaml entry
language: "en"
intents:
  CustomOutsideHumidity:
    data:
      - sentences:
          - "What is the humidity outside"

{% endraw %}

To teach Home Assistant how to handle the custom CustomOutsideHumidity {% term intent %}, create an intent_script entry in your {% term "configuration.yaml" %} file:

{% raw %}

# Example configuration.yaml entry
intent_script:
  CustomOutsideHumidity:
    speech:
      text: "It is currently {{ states('sensor.outside_humidity') }} percent humidity outside."

{% endraw %}

More complex actions can be done in intent_script, such as performing actions and firing events.

Extending built-in intents

Extending the built-in {% term intents %}, such as HassTurnOn and HassTurnOff, can be done as well.

For example, create the file config/custom_sentences/en/on_off.yaml and add:

{% raw %}

# Example on_off.yaml entry
language: "en"
intents:
  HassTurnOn:
    data:
      - sentences:
          - "engage [the] kitchen lights"
        slots:
          name: "kitchen lights"
  HassTurnOff:
    data:
      - sentences:
          - "disengage [the] kitchen lights"
        slots:
          name: "kitchen lights"

{% endraw %}

Now when you say "engage the kitchen lights", it will turn on a light named "kitchen lights". Saying "disengage kitchen lights" will turn it off.

Let's generalize this to other entities. The built-in {name} and {area} lists contain the names of your Home Assistant entities and areas.

Adding {name} to config/custom_sentences/en/on_off.yaml:

{% raw %}

# Example on_off.yaml entry
language: "en"
intents:
  HassTurnOn:
    data:
      - sentences:
          - "engage [the] {name}"
  HassTurnOff:
    data:
      - sentences:
          - "disengage [the] {name}"

{% endraw %}

You can now "engage" or "disengage" any entity.

Lastly, let's add sentences for turning lights on and off in specific areas:

{% raw %}

# Example on_off.yaml entry
language: "en"
intents:
  HassTurnOn:
    data:
      - sentences:
          - "engage [the] {name}"
      - sentences:
          - "engage [all] lights in [the] {area}"
        slots:
          name: "all"
          domain: "light"
  HassTurnOff:
    data:
      - sentences:
          - "disengage [the] {name}"
      - sentences:
          - "disengage [all] lights in [the] {area}"
        slots:
          name: "all"
          domain: "light"

{% endraw %}

It's now possible to say "engage all lights in the bedroom", which will turn on every light in the area named "bedroom".

Action conversation.process

Send a message to a conversation agent for processing.

Data attribute	Optional	Description
text	no	Transcribed text input
language	yes	Language of the text
agent_id	yes	ID of conversation agent. The conversation agent is the brains of the assistant. It processes the incoming text commands.
conversation_id	yes	ID of a new or previous conversation. Will continue an old conversation or start a new one.

This action is able to return response data. The response is the same response as for the /api/conversation/process API.

Action conversation.reload

Data attribute	Optional	Description
language	yes	Language to clear intent cache for. No value clears all languages
agent_id	yes	ID of conversation agent. Defaults to the built-in Home Assistant agent.