Exposing entities to voice assistants

Assist can only see and control the entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] that you expose to it. This way, you decide which devices you can control by voice. There’s one exception: a conversation agentSoftware that Home Assistant uses to understand a request and decide what to do. Home Assistant has a built-in conversation agent. Integrations can add others, including ones that use AI. Conversation agents that use AI can also use AI tools. Each assistant uses a conversation agent. [Learn more] with the Home Assistant set of AI toolsA function that conversation agents and AI apps can use to read information, control entities, or manage Home Assistant. AI tools are grouped into sets. Each set provides different functionality. Some sets only work for administrators. [Learn more] selected can reach all entities. This includes entities that you never exposed or stopped exposing. For details, refer to Sets of AI tools.

Entities that are exposed automatically

Home Assistant exposes common devicesA device is a model representing a physical or logical unit that contains entities. to AssistThe voice assistant built into Home Assistant. You can use Assist by talking or typing in the Home Assistant web interface and in the Home Assistant Companion app. You can also use it by talking through a voice satellite. You can set up several assistants, each with its own language and conversation agent. [Learn more] as you add them. This is the Expose new entities setting on the Assist card, under Settings > Voice assistants. It’s turned on by default.

When Expose new entities is turned on, Home Assistant exposes each new entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] of the following kinds to Assist:

  • Lights, switches, fans, covers, climate devices, humidifiers, water heaters, vacuums, media players, scenes, and to-do lists.
  • Binary sensors for doors, garage doors, windows, locks, and other openings, and binary sensors that detect motion or presence. These sensors only report a state. Assist can tell you if a door is open, but it can’t open or unlock anything with them.
  • Sensors that measure temperature, humidity, carbon monoxide, carbon dioxide, PM2.5, PM10, volatile organic compounds, or the air quality index.

CoversCovers are devices such as blinds, garage doors, etc that can be opened and closed and optionally set to a specific position. [Learn more] include garage doors and gates, so Home Assistant exposes them automatically too. If you don’t want to open them by voice, stop exposing them. For the steps, refer to Unexposing entities.

Home Assistant never exposes other entities automatically. For example, locks, alarm control panels, and scriptsA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more] stay unexposed until you expose them yourself. Configuration entities, diagnostic entities, and hidden entities are never exposed automatically either.

After an entity is added, it keeps its setting until you change it. You can expose or stop exposing any entity at any time.

The Alexa and Google Assistant cards have their own Expose new entities setting. It’s turned off by default.

Alexa and Google Assistant

With Home Assistant Cloud, you can also control your entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] with Alexa or Google Assistant. Each of them has its own card on the Voice assistants page, with its own exposure settings. You expose entities to them the same way as to AssistThe voice assistant built into Home Assistant. You can use Assist by talking or typing in the Home Assistant web interface and in the Home Assistant Companion app. You can also use it by talking through a voice satellite. You can set up several assistants, each with its own language and conversation agent. [Learn more].

To use Alexa or Google Assistant this way, you need the following:

  • You’re signed in to Home Assistant Cloud.
  • Alexa or Google Assistant is connected to Home Assistant Cloud:
    • For Alexa, the Home Assistant skill is enabled in the Alexa app. For the steps, refer to Alexa in the Home Assistant Cloud documentation.
    • For Google Assistant, the Home Assistant Cloud by Nabu Casa service is added in the Google Home app. For the steps, refer to Google Assistant in the Home Assistant Cloud documentation.
  • Alexa or Google Assistant is turned on in its card under Settings > Voice assistants.

If you set up Alexa or Google Assistant without Home Assistant Cloud, you choose the entities in YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the configuration.yaml or automations.yaml files. [Learn more] instead. For details, refer to Configure filter for Alexa and to the Google Assistant integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more].

Exposing entities to a voice assistant

You can expose several entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] at once from the Expose tab, or a single entity from its settings. Both work for AssistThe voice assistant built into Home Assistant. You can use Assist by talking or typing in the Home Assistant web interface and in the Home Assistant Companion app. You can also use it by talking through a voice satellite. You can set up several assistants, each with its own language and conversation agent. [Learn more], Alexa, and Google Assistant.

Exposing entities from the Expose tab

Use the Expose tab to expose several entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] at once, or entities that Home Assistant doesn’t expose automatically. For example, you added a smart lock, and you want to lock the front door with AssistThe voice assistant built into Home Assistant. You can use Assist by talking or typing in the Home Assistant web interface and in the Home Assistant Companion app. You can also use it by talking through a voice satellite. You can set up several assistants, each with its own language and conversation agent. [Learn more]. Or you just connected Alexa, and you want to ask it to turn on the living room lights. The tab also shows which entities a voice assistant can use.

Prerequisites:

To expose entities from the Expose tab:

  1. Go to Settings > Voice assistants.
  2. At the bottom of the card of the voice assistant, select the text that shows the number of exposed entities.
    • Result: The Expose tab opens. It only lists the entities that are exposed to that voice assistant.
    • For example, at the bottom of the Assist card, the text shows 12 entities exposed.
    • If the Alexa or Google Assistant card shows Show entities instead, you configured entity filters in your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file. In that case, you can’t change the exposed entities in the UI.
  3. In the lower-right corner, select Expose entities .
  4. Select the entities that you want to expose.
    • To find an entity, use the search field.
  5. Select Expose followed by the number of entities.
    • Result: The voice assistant can use these entities.
    • For example, the button shows Expose 3 entities.

Exposing a single entity from its settings

Use the settings of an entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] when you’re already working with that entity. For example, you just set up a new ceiling light and opened it from its deviceA device is a model representing a physical or logical unit that contains entities. page. You can expose it right there, without going to the Expose tab. In the same dialog, you can also add aliases, the other names that voice assistants understand for the entity.

Prerequisites:

  • An administrator account.
  • The entity has a unique ID. Entities without a unique ID have no voice assistant settings. To expose them, use the Expose tab.
  • For Alexa or Google Assistant: the requirements in Alexa and Google Assistant.

To expose a single entity from its settings:

  1. Open the entity.
  2. Select Settings .
  3. Select Voice assistants.
  4. Under Expose, turn on the voice assistant you want to use. If you only see the main Expose switch, use the Expose tab to choose a single assistant. The main switch exposes the entity to all supported assistants managed in the UI.
    • Result: The change takes effect right away.
    • For example, turn on Assist.
    • If a voice assistant shows Unsupported, it can’t control this kind of entity.
    • For doors, garage doors, and locks, Google Assistant also shows Ask for PIN. If you turn it on, Google Assistant asks for the PIN that you set under Security devices on the Google Assistant card.

Unexposing entities

Unexpose an entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] when you no longer want to control it by voice. For example, Home Assistant exposed a new garage door to AssistThe voice assistant built into Home Assistant. You can use Assist by talking or typing in the Home Assistant web interface and in the Home Assistant Companion app. You can also use it by talking through a voice satellite. You can set up several assistants, each with its own language and conversation agent. [Learn more] automatically, and you don’t want to open it by voice. Only the voice assistant that you choose stops using the entity. Unexposing doesn’t remove the entity from Home Assistant.

Prerequisites:

To unexpose entities:

  1. Go to Settings > Voice assistants.
  2. At the bottom of the card of the voice assistant, select the text that shows the number of exposed entities.
    • Result: The Expose tab opens. It only lists the entities that are exposed to that voice assistant.
  3. Select Enter selection mode .
  4. Select the entities.
  5. Select Unexpose, then select Unexpose again in the confirmation dialog.
    • Result: The voice assistant can no longer use these entities.
    • A conversation agentSoftware that Home Assistant uses to understand a request and decide what to do. Home Assistant has a built-in conversation agent. Integrations can add others, including ones that use AI. Conversation agents that use AI can also use AI tools. Each assistant uses a conversation agent. [Learn more] with the Home Assistant set of AI toolsA function that conversation agents and AI apps can use to read information, control entities, or manage Home Assistant. AI tools are grouped into sets. Each set provides different functionality. Some sets only work for administrators. [Learn more] can still reach them. For details, refer to Sets of AI tools.
    • To unexpose a single entity, you can also turn off the voice assistant in the settings of the entity, as described in Exposing a single entity from its settings.

Changing Expose new entities

Expose new entities decides whether Home Assistant exposes new entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] to a voice assistant as you add them. Each voice assistant has its own setting:

  • For AssistThe voice assistant built into Home Assistant. You can use Assist by talking or typing in the Home Assistant web interface and in the Home Assistant Companion app. You can also use it by talking through a voice satellite. You can set up several assistants, each with its own language and conversation agent. [Learn more], it’s turned on by default. If you want to decide on every entity yourself, turn it off. For example, you don’t want a new garage door to be exposed before you decide. For the kinds of entities that it exposes, refer to Entities that are exposed automatically.
  • For Alexa and Google Assistant, it’s turned off by default. If you want to control each new entity with them, turn it on. For example, you often add new lights and switches, and you want to control each one with Alexa without exposing it yourself. Home Assistant uses the same automatic exposure rules as for Assist.

Prerequisites:

To change Expose new entities:

  1. Go to Settings > Voice assistants.
  2. On the card of the voice assistant, turn Expose new entities on or off.
    • Result: The setting applies to the entities that you add from now on. Entities that you added before stay as they are.
    • To stop exposing entities that are already exposed, refer to Unexposing entities.