Home Assistant’s built-in sentences cover common commands, such as “turn on the kitchen lights.” Custom sentences let you add your own phrases, such as “movie night” to start a scene. There are two ways to do it: a sentence-trigger automation, which covers most needs, and custom sentence YAML files, which give you more control. Both work with the pipeline described in Home Assistant voice control.
Custom sentences run locally. You do not need an AI agent for them.
Sentence syntax
Both methods use the same syntax:
[optional words]can be left out. For example,[please] turn on the lampmatches with or without “please.”(alt1|alt2)matches either option. For example,turn on the (lamp|light).{slot}is a wildcard that captures words into a named slot. For example,play {album} by {artist}.
Case and most punctuation are ignored when matching. Leave punctuation out of your trigger sentences anyway, so they are easier to read.
Method 1: Sentence-trigger automation
This is the easiest method.
- Go to Settings > Automations & scenes and select Create automation.
- In the trigger list, choose Sentence. Enter one or more sentences. Each sentence will trigger the automation.
- To add a spoken reply, select Add action, scroll down to Other actions, and choose Set conversation response. Enter the text you want Assist to say. If the assistant has a text-to-speech engine, the reply is spoken through it. See text-to-speech options for choosing one.
- Save the automation.
You can use slots in the reply. If the trigger is play {album} by {artist}, the reply can be Playing {{ trigger.slots.album }} by {{ trigger.slots.artist }}.
Sentence triggers apply as soon as you save the automation.
To test, open Assist from the button at the top right of your dashboard and enter one of the sentences. If it does not work, check that what you entered matches one of the trigger sentences.
Method 2: Custom sentence YAML
Use YAML when an automation is not enough, such as when you want to extend a built-in intent or define a custom intent with its own response.
Custom sentence files go in config/custom_sentences/<language>/. For English, that is config/custom_sentences/en/. Each file starts with the language, then lists the intents and their sentences. This short example defines a custom intent called MovieNight:
language: "en"
intents:
MovieNight:
data:
- sentences:
- "movie night"
- "start movie night"
A custom intent does nothing on its own. Define what it does in configuration.yaml, using intent_script:
intent_script:
MovieNight:
speech:
text: "Enjoy the movie."
action:
- service: scene.turn_on
target:
entity_id: scene.movie_night
Change scene.movie_night to a scene that exists in your system. Reload the custom sentences with the conversation.reload action, or restart Home Assistant. After you change configuration.yaml, restart Home Assistant to be safe.
The same files can also define lists, which are sets of values for a slot, and expansion rules, which let you reuse a fragment of a sentence in several places. Check the Home Assistant documentation for the exact format.
You can also add sentences to built-in intents such as HassTurnOn, HassTurnOff, HassLightSet, HassGetState and HassStartTimer. This is useful when you want an extra way to ask for something the built-in sentences already handle.
Wildcards: watch out
A wildcard can swallow words it was not meant to. Put a wildcard at the end of a sentence, or place it between fixed words that mark its boundaries. The play {album} by {artist} pattern works because “by” shows where the album name ends. A pattern such as {name} {room} is harder, because the two wildcards have no clear boundary between them.
Testing and troubleshooting
Open Developer tools > Assist to test a sentence. It shows which intent matched and what each slot captured. This is the quickest way to see why a phrase does or does not work.
If a phrase still does not match:
- Check that you are saying exactly the sentence you wrote, without extra words.
- Check that the target entity is exposed to Assist.
- Add entity and area aliases. They often fix recognition problems without any custom sentences.
If you use Speech-to-Phrase, it learns sentence-trigger phrases, entity names and area names automatically, so a sentence trigger is recognized without extra setup.
Custom sentences and an AI agent
If the conversation agent is an AI model, sentence triggers are always checked first, but custom sentence YAML intents are checked first only when Prefer handling commands locally is turned on. Without that setting, the request goes to the model, which may not match your phrase the way you expect. For how to set this up, see how to connect ChatGPT to Home Assistant or AI in Home Assistant.
Common mistakes
- Custom intent YAML without a matching intent_script does nothing. Both parts are needed.
- Forgetting to expose entities. The command cannot find a device that is not exposed to Assist.
- Wildcards that are too greedy. See the section above.
- Assuming custom sentences need an LLM. They run locally.