112 lines
4.4 KiB
Markdown
112 lines
4.4 KiB
Markdown
---
|
|
layout: page
|
|
title: "Api.AI"
|
|
description: "Instructions how integrate api.ai with Home Assistant."
|
|
date: 2017-01-27 11:28
|
|
sidebar: true
|
|
comments: false
|
|
sharing: true
|
|
footer: true
|
|
logo: apiai.png
|
|
ha_category: Voice
|
|
featured: false
|
|
ha_release: 0.38
|
|
---
|
|
|
|
This component is designed to be used with the "webhook" integration in [api.ai][apiai-web]. When a conversation ends with an user, api.ai sends an action and parameters to the webhook.
|
|
|
|
api.ai requires a public endpoint (HTTPS recommended), so your Home Assistant should be exposed to Internet. api.ai will return fallback answers if your server do not answer, or takes too long (more than 5 seconds).
|
|
|
|
api.ai could be integrated with many popular messaging, virtual assistant and IoT platforms, eg.: Google Assistant (Google Actions), Skype, Messenger. [See here](https://docs.api.ai/docs/integrations) the complete list.
|
|
|
|
Using Api.ai will be easy to create conversations like:
|
|
|
|
> User: Which is the temperature at home?
|
|
>
|
|
> Bot: The temperature is 34 degrees
|
|
|
|
> User: Turn on the light
|
|
>
|
|
> Bot: In which room?
|
|
>
|
|
> User: In the kitchen
|
|
>
|
|
> Bot: Turning on kitchen light
|
|
|
|
To use this integration you should define a conversation (intent) in Api.ai, configure Home Assistant with the speech to return and, optionally, the action to execute.
|
|
|
|
### {% linkable_title Configuring your api.ai account %}
|
|
|
|
- [Login][apiai-web] with your Google account.
|
|
- Click on "Create Agent"
|
|
- Select name, language (if you are planning to use it with Google Actions check [here](https://support.google.com/assistant/answer/7108196?hl=en) supported languages) and time zone
|
|
- Click "Save"
|
|
- Go to "Fullfiment" (in the left menu)
|
|
- Enable Webhook and set your Home Assistant URL with the Api.ai endpoint. Eg.: ``https://myhome.duckdns.org/api/apiai?api_password=HA_PASSWORD``
|
|
- Click "Save"
|
|
- Create a new intent
|
|
- Below "User says" write one phrase that you, the user, will tell Api.ai. Eg.: Which is the temperature at home?
|
|
- In "Action" set some key (this will be the bind with Home Assistant configuration), eg.: GetTemperature
|
|
- In "Response" set "Cannot connect to Home Assistant or it is taking to long" (fall back response)
|
|
- At the end of the page, click on "Fulfillment" and check "Use webhook"
|
|
- Click "Save"
|
|
- On the top right, where is written "Try it now...", write, or say, the phrase you have previously defined and hit enter
|
|
- Api.ai has send a request to your Home Assistant server
|
|
|
|
Take a look to "Integrations", in the left menu, to configure third parties.
|
|
|
|
|
|
### {% linkable_title Configuring Home Assistant %}
|
|
|
|
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.
|
|
|
|
## {% linkable_title Examples %}
|
|
|
|
Download [this zip](https://github.com/home-assistant/home-assistant.github.io/blob/next/source/assets/HomeAssistant_APIAI.zip) and load it in your Api.ai agent (Settings -> Export and Import) for examples intents to use with this configuration:
|
|
|
|
```yaml
|
|
{% raw %}# Example configuration.yaml entry
|
|
apiai:
|
|
|
|
intent_script:
|
|
Temperature:
|
|
speech: The temperature at home is {{ states('sensor.home_temp') }} degrees
|
|
LocateIntent:
|
|
speech: >
|
|
{%- for state in states.device_tracker -%}
|
|
{%- if state.name.lower() == User.lower() -%}
|
|
{{ state.name }} is at {{ state.state }}
|
|
{%- elif loop.last -%}
|
|
I am sorry, I do not know where {{ User }} is.
|
|
{%- endif -%}
|
|
{%- else -%}
|
|
Sorry, I don't have any trackers registered.
|
|
{%- endfor -%}
|
|
WhereAreWeIntent:
|
|
speech: >
|
|
{%- if is_state('device_tracker.adri', 'home') and
|
|
is_state('device_tracker.bea', 'home') -%}
|
|
You are both home, you silly
|
|
{%- else -%}
|
|
Bea is at {{ states("device_tracker.bea") }}
|
|
and Adri is at {{ states("device_tracker.adri") }}
|
|
{% endif %}
|
|
TurnLights:
|
|
speech: Turning {{ Room }} lights {{ OnOff }}
|
|
action:
|
|
- service: notify.pushbullet
|
|
data_template:
|
|
message: Someone asked via apiai to turn {{ Room }} lights {{ OnOff }}
|
|
- service_template: >
|
|
{%- if OnOff == "on" -%}
|
|
switch.turn_on
|
|
{%- else -%}
|
|
switch.turn_off
|
|
{%- endif -%}
|
|
data_template:
|
|
entity_id: "switch.light_{{ Room | replace(' ', '_') }}"
|
|
{% endraw %}
|
|
```
|
|
|
|
[apiai-web]: https://api.ai/
|
|
[templates]: /topics/templating/
|