Document Assist satellite ask_question (#39733)

Co-authored-by: Franck Nijhof <git@frenck.dev> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2025-07-07 17:36:50 +00:00 · 2025-06-30 14:04:52 -05:00 · 2025-06-30 14:04:52 -05:00 · 3ae3772bcf
commit 3ae3772bcf
parent 39f38cb99f
1 changed files with 128 additions and 0 deletions
--- 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 %}
+