Conversation

The conversation 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 service 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 intentsIntent is a term used with voice assistants. The intent is what Home Assistant thinks you want it to do when it extracts a command from your voice or text utterance.
[Learn more] 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:

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

To teach Home Assistant how to handle the custom CustomOutsideHumidity intentIntent is a term used with voice assistants. The intent is what Home Assistant thinks you want it to do when it extracts a command from your voice or text utterance.
[Learn more], create an intent_script entry in your configuration.yaml file:

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

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

Extending built-in intents

Extending the built-in intentsIntent is a term used with voice assistants. The intent is what Home Assistant thinks you want it to do when it extracts a command from your voice or text utterance.
[Learn more], such as HassTurnOn and HassTurnOff, can be done as well.

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

# 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"

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:

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

You can now “engage” or “disengage” any entity.

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

# 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"

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

Service conversation.process

Send a message to a conversation agent for processing.

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

Service conversation.reload