Skip to content

Commit 80814f2

Browse files
balloobballoob
authored
update docs for intents (home-assistant#3046)
* update docs for intents * Fix alexa docs * Fix api.ai reference
1 parent 17eab64 commit 80814f2

File tree

10 files changed

+277
-190
lines changed

10 files changed

+277
-190
lines changed

‎source/_components/alexa.markdown

Lines changed: 23 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -15,42 +15,14 @@ ha_release: 0.10
1515

1616
There are a few ways that you can use Amazon Echo and Home Assistant together.
1717

18-
- [Turning devices on and off](#i-just-want-to-turn-devices-on-and-off-using-echo)
1918
- [Build custom commands to use](#i-want-to-build-custom-commands-to-use-with-echo)
2019
- [Create a new Flash Briefing source](#flash-briefing-skills)
21-
22-
No matter which method(s) you decide to use, please remember that Amazon Echo requires an active Internet connection to function. If your Internet is down or experiencing issues (or Amazon's infrastructure is having issues), none of these methods will work.
20+
- Alternative: use the [Emulated Hue component][emulated-hue-component] to trick Alexa to thinking Home Assistant is a Philips Hue hub.
2321

2422
Amazon has released [Echosim], a website that simulates the Alexa service in your browser. That way it is easy to test your skills without having access to a physical Amazon Echo.
2523

2624
[Echosim]: https://echosim.io/
2725

28-
## {% linkable_title I just want to turn devices on and off using Echo %}
29-
30-
If you just want to be able to turn anything with a switch (like lights, switches, media players, etc) on and off, you should enable the [Emulated Hue][emulated-hue-component] component. It makes your Home Assistant appear as if it were a Phillips Hue bridge, which Echo works with natively.
31-
32-
[emulated-hue-component]: https://home-assistant.io/components/emulated_hue/
33-
34-
Enabling the Emulated Hue component means you can turn things on and off by simply saying
35-
36-
> Alexa, turn the living room lights on.
37-
38-
or
39-
40-
> Alexa, set the living room lights to twenty percent.
41-
42-
instead of
43-
44-
> Alexa, tell Home Assistant to turn the living room lights on.
45-
46-
or
47-
48-
> Alexa, tell Home Assistant to set the living room lights to twenty percent.
49-
50-
In addition, you would need to build custom intents for each device and on/off combination using the below method, whereas everything just works without any extra work by using Emulated Hue.
51-
52-
Please note that you can use Emulated Hue and the built-in Alexa component side-by-side without issue if you wish.
53-
5426
## {% linkable_title I want to build custom commands to use with Echo %}
5527

5628
The built-in Alexa component allows you to integrate Home Assistant into Alexa/Amazon Echo. This component will allow you to query information and call services within Home Assistant by using your voice. Home Assistant offers no built-in sentences but offers a framework for you to define your own.
@@ -121,54 +93,7 @@ This means that we can now ask Alexa things like:
12193

12294
## {% linkable_title Configuring Home Assistant %}
12395

124-
Out of the box, the component will do nothing. You have to teach it about all intents you want it to answer to. The way it works is that the answer for each intent is based on [templates] that you define. Each template will have access to the existing states via the `states` variable but will also have access to all variables defined in the intent.
125-
126-
You can use [templates] for the values of `speech/text`, `card/title` and `card/content`.
127-
128-
Actions are using the [Home Assistant Script Syntax] and also have access to the variables from the intent.
129-
130-
[Home Assistant Script Syntax]: /getting-started/scripts/
131-
132-
Configuring the Alexa component for the above intents would look like this:
133-
134-
```yaml
135-
{% raw %}# Example configuration.yaml entry
136-
alexa:
137-
intents:
138-
WhereAreWeIntent:
139-
speech:
140-
type: plaintext
141-
text: >
142-
{%- if is_state('device_tracker.paulus', 'home') and
143-
is_state('device_tracker.anne_therese', 'home') -%}
144-
You are both home, you silly
145-
{%- else -%}
146-
Anne Therese is at {{ states("device_tracker.anne_therese") }}
147-
and Paulus is at {{ states("device_tracker.paulus") }}
148-
{% endif %}
149-
150-
LocateIntent:
151-
action:
152-
service: notify.notify
153-
data_template:
154-
message: The location of {{ User }} has been queried via Alexa.
155-
speech:
156-
type: plaintext
157-
text: >
158-
{%- for state in states.device_tracker -%}
159-
{%- if state.name.lower() == User.lower() -%}
160-
{{ state.name }} is at {{ state.state }}
161-
{%- elif loop.last -%}
162-
I am sorry, I do not know where {{ User }} is.
163-
{%- endif -%}
164-
{%- else -%}
165-
Sorry, I don't have any trackers registered.
166-
{%- endfor -%}
167-
card:
168-
type: simple
169-
title: Sample title
170-
content: Some more content{% endraw %}
171-
```
96+
When activated, the Alexa component will have Home Assistant's native intent support handle the incoming intents. If you want to run actions based on intents, use the [`intent_script`](/components/intent_script) component.
17297

17398
### {% linkable_title Working With Scenes %}
17499

@@ -203,17 +128,18 @@ Add a sample utterance:
203128
ActivateSceneIntent activate {Scene}
204129
```
205130

206-
Then add the intent to your Alexa Section in your HA config file:
131+
Then add the intent to your intent_script section in your HA config file:
207132

208133
```yaml
209-
ActivateSceneIntent:
210-
action:
211-
service: scene.turn_on
212-
data_template:
213-
entity_id: scene.{% raw %}{{ Scene | replace(" ", "_") }}{% endraw %}
214-
speech:
215-
type: plaintext
216-
text: OK
134+
intent_script:
135+
ActivateSceneIntent:
136+
action:
137+
service: scene.turn_on
138+
data_template:
139+
entity_id: scene.{% raw %}{{ Scene | replace(" ", "_") }}{% endraw %}
140+
speech:
141+
type: plain
142+
text: OK
217143
```
218144
219145
Here we are using [templates] to take the name we gave to Alexa e.g. `downstairs on` and replace the space with an underscore so it becomes `downstairs_on` as Home Assistant expects.
@@ -250,17 +176,18 @@ Add a sample utterance:
250176
RunScriptIntent run {Script}
251177
```
252178

253-
Then add the intent to your Alexa Section in your HA config file:
179+
Then add the intent to your intent_script section in your HA config file:
254180

255181
```yaml
256-
RunScriptIntent:
257-
action:
258-
service: script.turn_on
259-
data_template:
260-
entity_id: script.{% raw %}{{ Script | replace(" ", "_") }}{% endraw %}
261-
speech:
262-
type: plaintext
263-
text: OK
182+
intent_script:
183+
RunScriptIntent:
184+
action:
185+
service: script.turn_on
186+
data_template:
187+
entity_id: script.{% raw %}{{ Script | replace(" ", "_") }}{% endraw %}
188+
speech:
189+
type: plain
190+
text: OK
264191
```
265192

266193
Now say `Alexa ask homeassistant to run <some script>` and Alexa will run that script for you.
@@ -306,35 +233,6 @@ text: !include alexa_confirm.yaml
306233

307234
Alexa will now respond with a random phrase each time. You can use the include for as many different intents as you like so you only need to create the list once.
308235

309-
<p class='note'>
310-
As of April 2017, the random filter has been somewhat broken. You'll get a random response the first time this runs, but subsequent commands will reply with the same randomly-chosen phrase. On reboot, Home Assistant will pick a new random choice, but you're stuck with that choice till you reboot. To get around that, use the following code in alexa_confirm.yaml:
311-
</p>
312-
313-
```text
314-
{% raw %} >
315-
{% set responses = [
316-
"OK",
317-
"Sure",
318-
"If you insist",
319-
"Done",
320-
"No worries",
321-
"I can do that",
322-
"Leave it to me",
323-
"Consider it done",
324-
"As you wish",
325-
"By your command",
326-
"Affirmative",
327-
"Yes oh revered one",
328-
"I will",
329-
"As you decree, so shall it be",
330-
"No Problem"
331-
] %}
332-
{% set rindex = (range(0, (responses | length - 1) )|random) -%}
333-
{{responses[rindex]}}
334-
{% endraw %}
335-
```
336-
337-
338236
## {% linkable_title Flash Briefing Skills %}
339237

340238
As of version [0.31][zero-three-one] Home Assistant supports the new [Alexa Flash Briefing Skills API][flash-briefing-api]. A Flash Briefing Skill adds a new Flash Briefing source that is generated by Home Assistant.
@@ -395,3 +293,4 @@ Please refer to the [Amazon documentation][flash-briefing-api-docs] for more inf
395293
[templates]: /topics/templating/
396294
[zero-three-one]: /blog/2016/10/22/flash-briefing-updater-hacktoberfest/
397295
[alexa-settings-site]: http://alexa.amazon.com/
296+
[emulated-hue-component]: /components/emulated_hue/

‎source/_components/apiai.markdown

Lines changed: 38 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -58,35 +58,7 @@ Take a look to "Integrations", in the left menu, to configure third parties.
5858

5959
### {% linkable_title Configuring Home Assistant %}
6060

61-
Out of the box, the component will do nothing. You have to teach it about all intents you want it to answer to. The way it works is that the answer for each intent is based on [templates] that you define. Each template will have access to the existing states via the `states` variable but will also have access to all variables defined in the intent.
62-
63-
You can use [templates] for setting `speech`.
64-
65-
Actions are using the [Home Assistant Script Syntax] and also have access to the variables from the intent.
66-
67-
[Home Assistant Script Syntax]: /getting-started/scripts/
68-
69-
Example of an Api.ai for the above configuration:
70-
71-
```yaml
72-
{% raw %}# Example configuration.yaml entry
73-
apiai:
74-
intents:
75-
GetTemperature:
76-
speech: We have {{ states.sensor.temperature }} degrees
77-
async_action: False
78-
action:
79-
service: notify.notify
80-
data_template:
81-
message: Api.ai has send a request
82-
{% endraw %}
83-
```
84-
85-
Inside an intent we can define this variables:
86-
- **speech** (*Optional*): Text or template to return to Api.ai
87-
- **action** (*Optional*): Script definition
88-
- **async_action** (*Optional*): If Home Assistant should execute the action asynchronously (returning response to Api.ai without waiting the action to finish). Should be set to `True` if Api.ai is returning the "Cannot connect to Home Assistant or it is taking to long" message, but then you will not be able to use values based on the result of the action. Defaults to `False`.
89-
61+
When activated, the Alexa component will have Home Assistant's native intent support handle the incoming intents. If you want to run actions based on intents, use the [`intent_script`](/components/intent_script) component.
9062

9163
## {% linkable_title Examples %}
9264

@@ -95,43 +67,44 @@ Download [this zip](https://github.com/home-assistant/home-assistant.github.io/b
9567
```yaml
9668
{% raw %}# Example configuration.yaml entry
9769
apiai:
98-
intents:
99-
Temperature:
100-
speech: The temperature at home is {{ states('sensor.home_temp') }} degrees
101-
LocateIntent:
102-
speech: >
103-
{%- for state in states.device_tracker -%}
104-
{%- if state.name.lower() == User.lower() -%}
105-
{{ state.name }} is at {{ state.state }}
106-
{%- elif loop.last -%}
107-
I am sorry, I do not know where {{ User }} is.
70+
71+
intent_script:
72+
Temperature:
73+
speech: The temperature at home is {{ states('sensor.home_temp') }} degrees
74+
LocateIntent:
75+
speech: >
76+
{%- for state in states.device_tracker -%}
77+
{%- if state.name.lower() == User.lower() -%}
78+
{{ state.name }} is at {{ state.state }}
79+
{%- elif loop.last -%}
80+
I am sorry, I do not know where {{ User }} is.
81+
{%- endif -%}
82+
{%- else -%}
83+
Sorry, I don't have any trackers registered.
84+
{%- endfor -%}
85+
WhereAreWeIntent:
86+
speech: >
87+
{%- if is_state('device_tracker.adri', 'home') and
88+
is_state('device_tracker.bea', 'home') -%}
89+
You are both home, you silly
90+
{%- else -%}
91+
Bea is at {{ states("device_tracker.bea") }}
92+
and Adri is at {{ states("device_tracker.adri") }}
93+
{% endif %}
94+
TurnLights:
95+
speech: Turning {{ Room }} lights {{ OnOff }}
96+
action:
97+
- service: notify.pushbullet
98+
data_template:
99+
message: Someone asked via apiai to turn {{ Room }} lights {{ OnOff }}
100+
- service_template: >
101+
{%- if OnOff == "on" -%}
102+
switch.turn_on
103+
{%- else -%}
104+
switch.turn_off
108105
{%- endif -%}
109-
{%- else -%}
110-
Sorry, I don't have any trackers registered.
111-
{%- endfor -%}
112-
WhereAreWeIntent:
113-
speech: >
114-
{%- if is_state('device_tracker.adri', 'home') and
115-
is_state('device_tracker.bea', 'home') -%}
116-
You are both home, you silly
117-
{%- else -%}
118-
Bea is at {{ states("device_tracker.bea") }}
119-
and Adri is at {{ states("device_tracker.adri") }}
120-
{% endif %}
121-
TurnLights:
122-
speech: Turning {{ Room }} lights {{ OnOff }}
123-
action:
124-
- service: notify.pushbullet
125-
data_template:
126-
message: Someone asked via apiai to turn {{ Room }} lights {{ OnOff }}
127-
- service_template: >
128-
{%- if OnOff == "on" -%}
129-
switch.turn_on
130-
{%- else -%}
131-
switch.turn_off
132-
{%- endif -%}
133-
data_template:
134-
entity_id: "switch.light_{{ Room | replace(' ', '_') }}"
106+
data_template:
107+
entity_id: "switch.light_{{ Room | replace(' ', '_') }}"
135108
{% endraw %}
136109
```
137110

‎source/_components/intent_script.markdown

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
layout: page
3+
title: "Intent Script"
4+
description: "Instructions on how to setup scripts to run on intents."
5+
date: 2016-02-10 17:11
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
logo: home-assistant.png
11+
ha_category: Intent
12+
ha_release: 0.50
13+
---
14+
15+
The intent_script component allows users to configure actions and responses to intents. Intents can be fired by any component that supports it. Examples are Alexa (Amazon Echo), API.ai (Google Assistant) and Snips.
16+
17+
```yaml
18+
{% raw %}# Example configuration.yaml entry
19+
intent_script:
20+
GetTemperature: # Intent type
21+
speech:
22+
text: We have {{ states.sensor.temperature }} degrees
23+
action:
24+
service: notify.notify
25+
data_template:
26+
message: Hello from an intent!
27+
{% endraw %}
28+
```
29+
30+
Inside an intent we can define these variables:
31+
- **speech** (*Optional*): Text or template to return
32+
- **action** (*Optional*): [Script syntax]
33+
- **async_action** (*Optional*): Set to True to have Home Assistant not wait for the script to finish before returning the intent response.
34+
35+
[Script syntax]: /docs/scripts/

‎source/_components/snips.markdown

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ mqtt:
100100
```
101101
### Triggering actions
102102
103-
In Home Assistant, we trigger actions based on intents produced by Snips. This is done in `configuration.yaml`. For instance, the following block handles `ActivateLightColors` intents (included in the Snips IoT intent bundle) to change light colors:
103+
In Home Assistant, we trigger actions based on intents produced by Snips using the [`intent_script`](/components/intent_script) component. For instance, the following block handles `ActivateLightColors` intents (included in the Snips IoT intent bundle) to change light colors:
104104

105105
```yaml
106106
snips:

‎source/_includes/asides/developers_navigation.html

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,14 @@ <h1 class="title delta">Development Guide</h1>
5454
<li>{% active_link /developers/component_discovery/ Component Discovery %}</li>
5555
</ul>
5656
</li>
57+
<li>
58+
{% active_link /developers/intent/ Intents (handling voice responses) %}
59+
<ul>
60+
<li>{% active_link /developers/intent/firing/ Firing intents %}</li>
61+
<li>{% active_link /developers/intent/handling/ Handling intents %}</li>
62+
<li>{% active_link /developers/intent/conversation/ Registering sentences %}</li>
63+
</ul>
64+
</li>
5765
<li>
5866
{% active_link /developers/asyncio/ Asynchronous Programming %}
5967
<ul>

0 commit comments

Comments
 (0)