diff --git a/source/_integrations/assist_satellite.markdown b/source/_integrations/assist_satellite.markdown index 9cdbd19935b..16e20de302a 100644 --- a/source/_integrations/assist_satellite.markdown +++ b/source/_integrations/assist_satellite.markdown @@ -112,3 +112,131 @@ target: extra_system_prompt: "The user has left the lights on in the living room and is being asked if they'd like to turn them off." preannounce: false # chime disabled ``` + +### Action `assist_satellite.ask_question` + +The {% my developer_call_service service="assist_satellite.ask_question" %} action asks a question on the satellite, listens for a response, and matches it against a predefined list of possible answers. Information about the matched answer is stored in a `response_variable` so the appropriate next steps can be taken in your automation or script. + +The question may be provided as text or a media id. If text is used, it will first be converted to a media id using the [text-to-speech](/integrations/tts) system of the satellite's configured [pipeline](/voice_control/voice_remote_local_assistant/). + +Audio from the user's response is transcribed using the [speech-to-text](/integrations/stt) system of the satellite's configured [pipeline](/voice_control/voice_remote_local_assistant/). + +The `answers` are given as a list of objects with the following structure: + +- `id` - unique id of the answer +- `sentences` - list of [sentence templates](https://developers.home-assistant.io/docs/voice/intent-recognition/template-sentence-syntax/#sentence-templates-syntax) + +Sentence templates may contain wildcard `{slots}` that will be stored in the answer's `slots` field. For example, `play {album} by {artist}` will match "play the white album by the beatles" with "white album" stored in `slots.album` and "the beatles" in `slots.artist`. + +The matched answer will be stored in a `response_variable` with the structure: + +- `id` - unique id of the matching answer (or `None` if no match) +- `sentence` - response text from user +- `slots` - values of wildcard `{slots}` from matching answer + +{% my developer_call_service badge service="assist_satellite.ask_question" %} + +Examples in YAML: + +{% raw %} + +```yaml +actions: + - action: assist_satellite.ask_question + data: + question: "Welcome home! What kind of music would you like to listen to?" + entity_id: assist_satellite.my_entity + answers: + - id: jazz + sentences: + - "[some] jazz [music] [please]" + - "something spicy" + - id: rock + sentences: + - "[some] rock [music] [please]" + - "something with a beat" + - id: nothing + sentences: + - "nothing [for now] [please]" + - "nevermind" + - "cancel" + response_variable: answer + - choose: + - conditions: + - condition: template + value_template: "{{ answer.id == 'jazz' }}" + sequence: + - action: play_jazz_action + - conditions: + - condition: template + value_template: "{{ answer.id == 'rock' }}" + sequence: + - action: play_rock_action + default: + - action: assist_satellite.announce + data: + message: "OK, maybe some other time." + target: + entity_id: assist_satellite.my_entity +``` + +{%endraw %} + + +Instead of text, the question can also be a media ID: + +```yaml +action: assist_satellite.ask_question +data: + entity_id: assist_satellite.my_entity + question_media_id: ITEM_ID + answers: ANSWERS +response_variable: answer +``` + +A chime is automatically played before the question. You can override this with your own sound by setting `preannounce_media_id`, or disable the chime entirely by setting `preannounce` to `false`. + +Examples in YAML: + +```yaml +action: assist_satellite.ask_question +data: + entity_id: assist_satellite.my_entity + preannounce_media_id: ITEM_ID # custom chime + question: QUESTION + answers: ANSWERS +response_variable: answer +``` + +```yaml +action: assist_satellite.ask_question +data: + entity_id: assist_satellite.my_entity + preannounce: false # chime disabled + question: QUESTION + answers: ANSWERS +response_variable: answer +``` + +If `answers` is omitted, the response text from the user will be available in the `sentence` text of the `response_variable`. + +Examples in YAML: + +{% raw %} + +```yaml +actions: + - action: assist_satellite.ask_question + data: + question: "Say something" + entity_id: assist_satellite.my_entity + response_variable: answer + - action: assist_satellite.announce + data: + message: "You said {{ answer.sentence }}" + target: + entity_id: assist_satellite.my_entity +``` + +{% endraw %} +