Assist - custom sentences

You may add your own sentences to the intent recognizer by either extending an existing intent or creating a new one. You may also customize responses for existing intents.

Adding a custom sentence to trigger an automation

This is the easiest method to get started with custom sentences for automations.

Prerequisites

If you have not set up voice control yet, set up the hardware first. For instructions, refer to one of the following tutorials:

World’s most private voice assistant: Using a classic landline phone
$13 voice assistant for Home Assistant: Using a button with speaker and mic
S3-BOX-3 voice assistant: Using a small device with speaker, mic, and display
Assist for Apple: Using your iPhone, Mac, or Apple watch
Assist for Android: Using your Android phone, tablet, or a Wear OS watch

To add a custom sentence to trigger an automation

Under Settings > Automations & Scenes, in the bottom right corner, select Create automation.
In the Trigger drop-down menu, select Sentence.
Enter one or more sentences that you would like to trigger an automation.
- Do not use punctuation.
- You can add multiple sentences. They will then all trigger that automation.
To add a custom response, select Add action. Scroll all the way down and select Other actions.
- Then, select Set conversation response.
In the text field, enter the response you want to hear from Assist and select Save.
- You can also use wildcards. For example, the trigger:
```
play {album} by {artist}
```
  could have the response:
```
Playing {{ trigger.slots.album }} by {{ trigger.slots.artist }}
```
- For more details, refer to conversation response script action.
To test the automation, go to Overview and in the top right corner, open Assist.
- Enter one of the sentences.
If it did not work out, checkout the troubleshooting section.
- One of the causes could be that the device you’re targeting has not been exposed to Assist.
Pick up your voice control device and speak the custom sentence.
- Your automation should now be triggered.

Setting up custom sentences in configuration.yaml

Intents and sentences may be added in the conversation config in your configuration.yaml file:

# Example configuration.yaml
conversation:
  intents:
    HassTurnOn:
      - "activate [the] {name}"

This extends the default English sentences for the HassTurnOn intent, allowing you to say “activate the kitchen lights” as well as “turn on the kitchen lights”.

New intents can also be added, with their responses and actions defined using the intent_script integration:

# Example configuration.yaml
conversation:
  intents:
    YearOfVoice:
      - "how is the year of voice going"
      
intent_script:
  YearOfVoice:
    speech:
      text: "Great! We're at over 40 languages and counting."

Besides a text response, intent_script can trigger any action available in Home Assistant, such as calling a service or firing an event.

Setting up sentences in the config directory

More advanced customization can be done in Home Assistant’s config directory. YAML files in config/custom_sentences/en, for example, will be loaded when English sentences (language code en) are requested.

The following example creates a new SetVolume intent that changes the volume on one of two media players:

# Example config/custom_sentences/en/media.yaml
language: "en"
intents:
  SetVolume:
    data:
      - sentences:
          - "(set|change) {media_player} volume to {volume} [percent]"
          - "(set|change) [the] volume for {media_player} to {volume} [percent]"
lists:
  media_player:
    values:
      - in: "living room"
        out: "media_player.living_room"
      - in: "bedroom"
        out: "media_player.bedroom"
  volume:
    range:
      from: 0
      to: 100

As mentioned above, you can then use the intent_script integration to implement an action and provide a response for SetVolume:

# Example configuration.yaml
intent_script:
  SetVolume:
    action:
      service: "media_player.volume_set"
      data:
        entity_id: "{{ media_player }}"
        volume_level: "{{ volume / 100.0 }}"
    speech:
      text: "Volume changed to {{ volume }}"

Customizing responses

Responses for existing intents can be customized as well in config/custom_sentences/<language>:

# Example config/custom_sentences/en/responses.yaml
language: "en"
responses:
  intents:
    HassTurnOn:
      default: "I have turned on the {{ slots.name }}"