Skip to main content

Conversation entity

A conversation entity allows users to converse with Home Assistant.

A conversation entity is derived from the homeassistant.components.conversation.ConversationEntity.

Properties

tip

Properties should always only return information from memory and not do I/O (like network requests).

NameTypeDefaultDescription
supported_languageslist[str] | Literal["*"]RequiredThe supported languages of the service. Return "*" if you support all.

Supported features

Supported features are defined by using values in the ConversationEntityFeature enum and are combined using the bitwise or (|) operator.

ValueDescription
CONTROLThe entity is able to control Home Assistant.

Methods

Process

This method is used to process an incoming chat message.

class MyConversationEntity(ConversationEntity):
"""Represent a conversation entity."""

async def async_process(self, user_input: ConversationInput) -> ConversationResult:
"""Process a sentence."""
response = intent.IntentResponse(language=user_input.language)
response.async_set_speech("Test response")
return agent.ConversationResult(
conversation_id=None,
response=response
)

A ConversationInput object contains the following data:

NameTypeDescription
textstrUser input
contextContextHA context to attach to actions in HA
conversation_idOptional[str]Can be used to track a multi-turn conversation. Return None if not supported
languagestrLanguage of the text. If user did not provide one, it's set to the HA configured language.

Prepare

As soon as Home Assistant knows a request is coming in, we will let the conversation entity prepare for it. This can be used to load a language model or other resources. This function is optional to implement.

class MyConversationEntity(ConversationEntity):
"""Represent a conversation entity."""

async def async_prepare(self, language: str | None = None) -> None:
"""Prepare a language for processing."""