From 161e804852774bf39e61ac72f71bb139749bbad8 Mon Sep 17 00:00:00 2001 From: Michael Hansen Date: Thu, 26 Jun 2025 14:17:24 -0500 Subject: [PATCH 1/7] Add docs for Assist satellite ask_question --- .../_integrations/assist_satellite.markdown | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/source/_integrations/assist_satellite.markdown b/source/_integrations/assist_satellite.markdown index 9cdbd19935bb..75db8b23c502 100644 --- a/source/_integrations/assist_satellite.markdown +++ b/source/_integrations/assist_satellite.markdown @@ -112,3 +112,97 @@ 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 pre-defined 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: + +```yaml +action: assist_satellite.ask_question +data: + entity_id: assist_satellite.my_entity + question: "Welcome home! What kind of music would you like to listen to?" + 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 +``` + +```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.start_conversation +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: + +```yaml +action: assist_satellite.start_conversation +data: + entity_id: assist_satellite.my_entity + question: QUESTION +response_variable: answer + +# do something with answer.sentence +``` From 0f7c78e59a5aed863adf0f6ab63544c27f784143 Mon Sep 17 00:00:00 2001 From: Michael Hansen Date: Thu, 26 Jun 2025 14:20:12 -0500 Subject: [PATCH 2/7] Fix list marker --- source/_integrations/assist_satellite.markdown | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/_integrations/assist_satellite.markdown b/source/_integrations/assist_satellite.markdown index 75db8b23c502..01137e283a50 100644 --- a/source/_integrations/assist_satellite.markdown +++ b/source/_integrations/assist_satellite.markdown @@ -123,16 +123,16 @@ Audio from the user's response is transcribed using the [speech-to-text](/integr 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) +- `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 +- `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" %} From 28482c30cd55f25a4b35cd1325b34ad97ff656d7 Mon Sep 17 00:00:00 2001 From: Michael Hansen Date: Thu, 26 Jun 2025 14:32:18 -0500 Subject: [PATCH 3/7] Fix YAML examples --- source/_integrations/assist_satellite.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/assist_satellite.markdown b/source/_integrations/assist_satellite.markdown index 01137e283a50..027e97ef3c18 100644 --- a/source/_integrations/assist_satellite.markdown +++ b/source/_integrations/assist_satellite.markdown @@ -184,7 +184,7 @@ response_variable: answer ``` ```yaml -action: assist_satellite.start_conversation +action: assist_satellite.ask_question data: entity_id: assist_satellite.my_entity preannounce: false # chime disabled @@ -198,7 +198,7 @@ If `answers` is omitted, the response text from the user will be available in th Examples in YAML: ```yaml -action: assist_satellite.start_conversation +action: assist_satellite.ask_question data: entity_id: assist_satellite.my_entity question: QUESTION From 0ae195cb7ec735a64fd28b5399c7842a42ecae76 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Fri, 27 Jun 2025 10:42:33 +0200 Subject: [PATCH 4/7] Update source/_integrations/assist_satellite.markdown Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- source/_integrations/assist_satellite.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/assist_satellite.markdown b/source/_integrations/assist_satellite.markdown index 027e97ef3c18..61eeaca38036 100644 --- a/source/_integrations/assist_satellite.markdown +++ b/source/_integrations/assist_satellite.markdown @@ -115,7 +115,7 @@ target: ### 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 pre-defined 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 {% 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/). From 84b511937f99e1193ce554d73f3fc6a88e4adb3d Mon Sep 17 00:00:00 2001 From: Michael Hansen Date: Mon, 30 Jun 2025 13:46:03 -0500 Subject: [PATCH 5/7] Add example with choose --- .../_integrations/assist_satellite.markdown | 76 ++++++++++++------- 1 file changed, 50 insertions(+), 26 deletions(-) diff --git a/source/_integrations/assist_satellite.markdown b/source/_integrations/assist_satellite.markdown index 61eeaca38036..879d13cb1575 100644 --- a/source/_integrations/assist_satellite.markdown +++ b/source/_integrations/assist_satellite.markdown @@ -139,27 +139,47 @@ The matched answer will be stored in a `response_variable` with the structure: Examples in YAML: ```yaml -action: assist_satellite.ask_question -data: - entity_id: assist_satellite.my_entity - question: "Welcome home! What kind of music would you like to listen to?" - 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 +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 ``` +Instead of text, the question can also be a media id: + ```yaml action: assist_satellite.ask_question data: @@ -198,11 +218,15 @@ If `answers` is omitted, the response text from the user will be available in th Examples in YAML: ```yaml -action: assist_satellite.ask_question -data: - entity_id: assist_satellite.my_entity - question: QUESTION -response_variable: answer - -# do something with answer.sentence +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 ``` From 29a4e003ec291ce1c084fe8371a092d3bbd81b69 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Mon, 30 Jun 2025 21:00:59 +0200 Subject: [PATCH 6/7] micro tweak --- source/_integrations/assist_satellite.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/assist_satellite.markdown b/source/_integrations/assist_satellite.markdown index 879d13cb1575..eab4bece5673 100644 --- a/source/_integrations/assist_satellite.markdown +++ b/source/_integrations/assist_satellite.markdown @@ -178,7 +178,7 @@ actions: entity_id: assist_satellite.my_entity ``` -Instead of text, the question can also be a media id: +Instead of text, the question can also be a media ID: ```yaml action: assist_satellite.ask_question From 4d02ba3e58d74f18090e9c8c28519cf02a6fd660 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Mon, 30 Jun 2025 21:02:32 +0200 Subject: [PATCH 7/7] Fix CI --- source/_integrations/assist_satellite.markdown | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/_integrations/assist_satellite.markdown b/source/_integrations/assist_satellite.markdown index eab4bece5673..16e20de302ab 100644 --- a/source/_integrations/assist_satellite.markdown +++ b/source/_integrations/assist_satellite.markdown @@ -138,6 +138,8 @@ The matched answer will be stored in a `response_variable` with the structure: Examples in YAML: +{% raw %} + ```yaml actions: - action: assist_satellite.ask_question @@ -178,6 +180,9 @@ actions: entity_id: assist_satellite.my_entity ``` +{%endraw %} + + Instead of text, the question can also be a media ID: ```yaml @@ -217,6 +222,8 @@ If `answers` is omitted, the response text from the user will be available in th Examples in YAML: +{% raw %} + ```yaml actions: - action: assist_satellite.ask_question @@ -230,3 +237,6 @@ actions: target: entity_id: assist_satellite.my_entity ``` + +{% endraw %} +