Skip to content

Document Assist satellite ask_question #39733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 30, 2025
Merged

Document Assist satellite ask_question #39733

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
161e804
Add docs for Assist satellite ask_question
synesthesiam Jun 26, 2025
0f7c78e
Fix list marker
synesthesiam Jun 26, 2025
28482c3
Fix YAML examples
synesthesiam Jun 26, 2025
0ae195c
Update source/_integrations/assist_satellite.markdown
frenck Jun 27, 2025
84b5119
Add example with choose
synesthesiam Jun 30, 2025
29a4e00
micro tweak
frenck Jun 30, 2025
4d02ba3
Fix CI
frenck Jun 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 128 additions & 0 deletions source/_integrations/assist_satellite.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +141 to +163
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Move entity_id to target: and keep parameters under data:

Current example places entity_id under data: and mixes service parameters in the same block.
The canonical Home Assistant service-call shape is:

action: <service>
target:
  entity_id: <entity>
data:
  <service-specific-fields>

Applying that pattern keeps these docs consistent with all other integration pages and with the UI-generated YAML, reducing copy/paste errors.

-    data:
-      question: "Welcome home! What kind of music would you like to listen to?"
-      entity_id: assist_satellite.my_entity
-      answers:
+    target:
+      entity_id: assist_satellite.my_entity
+    data:
+      question: "Welcome home! What kind of music would you like to listen to?"
+      answers:

Replicate the same split for the default branch’s assist_satellite.announce call (move entity_id out of data:).

🤖 Prompt for AI Agents 
In source/_integrations/assist_satellite.markdown between lines 141 and 163, the
YAML example incorrectly places entity_id under data:, mixing it with service
parameters. To fix this, move entity_id under a new target: key, separate from
data:, which should only contain service-specific fields. Also, apply the same
change to the default branch’s assist_satellite.announce call by moving its
entity_id out of data: into target: to maintain consistency with Home
Assistant's canonical service-call structure.

- 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
```
Comment on lines +188 to +195
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Same entity/parameter separation applies here

For consistency (and to match what the automation editor produces) please move entity_id to target: and keep question_media_id/answers under data:.

🤖 Prompt for AI Agents 
In source/_integrations/assist_satellite.markdown around lines 188 to 195, the
YAML structure places entity_id under data, but for consistency and to match the
automation editor, move entity_id out of data and place it under a new target:
key, while keeping question_media_id and answers under data:. Adjust the
indentation accordingly to reflect this separation.


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
```
Comment on lines +201 to +209
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

YAML style consistency – target vs data

This example still mixes entity_id with other parameters. Align with the previous suggestion so readers don’t have to mentally switch styles between snippets.

🤖 Prompt for AI Agents 
In source/_integrations/assist_satellite.markdown around lines 201 to 209, the
YAML example uses `data` to group parameters but includes `entity_id` inside it,
mixing styles. To fix this, move `entity_id` out of the `data` section and place
it at the same level as `action` and `response_variable`, aligning with the
previous examples for consistent YAML style.


```yaml
action: assist_satellite.ask_question
data:
entity_id: assist_satellite.my_entity
preannounce: false # chime disabled
question: QUESTION
answers: ANSWERS
response_variable: answer
```
Comment on lines +211 to +219
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Final example: apply the same structural correction

Keeping one consistent snippet style throughout the page prevents confusion and avoids inadvertent misconfiguration.

🤖 Prompt for AI Agents 
In source/_integrations/assist_satellite.markdown around lines 211 to 219, the
YAML snippet style is inconsistent with the rest of the page. Update this
snippet to match the consistent snippet style used elsewhere on the page to
maintain uniformity and prevent confusion or misconfiguration.


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 %}