From 49b6b63769b1ff3710e9608df1bc9714146ec78e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A1n=20L=C3=B3pez?= Date: Sun, 12 Feb 2017 08:34:57 +0100 Subject: [PATCH] Add doc for api.ai component (#1888) * Add doc for api.ai component * More examples --- source/_components/apiai.markdown | 135 +++++++++++++++++++++++ source/images/supported_brands/apiai.png | Bin 0 -> 3062 bytes 2 files changed, 135 insertions(+) create mode 100644 source/_components/apiai.markdown create mode 100644 source/images/supported_brands/apiai.png diff --git a/source/_components/apiai.markdown b/source/_components/apiai.markdown new file mode 100644 index 00000000000..7216ad35d4f --- /dev/null +++ b/source/_components/apiai.markdown @@ -0,0 +1,135 @@ +--- +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: true +ha_release: 0.37 +--- + +This component is designed to be used with the "webhook" integration in api.ai. 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 fall back 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 HA url with the apiai 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 HA config), eg.: GetTemperature +- In "Response" set "Cannot connect to HA 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 HA server + +Take a look to "Integrations", in the left menu, to configure third parties. + + +### {% linkable_title Configuring Home Assistant %} +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. + +You can use [templates] for setting `speech`. + +Actions are using the [Home Assistant Script Syntax] and also have access to the variables from the intent. + +[Home Assistant Script Syntax]: /getting-started/scripts/ + +Example of an Api.ai for the above configuration: + +```yaml +{% raw %}# Example configuration.yaml entry +apiai: + intents: + GetTemperature: + speech: We have {{ states.sensor.temperature }} degrees + async_action: False + action: + service: notify.notify + data_template: + message: Api.ai has send a request +{% endraw %} +``` + +Inside an intent we can define this variables: +- **speech** (*Optional*): Text or template to return to Api.ai +- **action** (*Optional*): Script definition +- **async_action** (*Optional*): If HA 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 HA 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`. + + +## {% linkable_title Examples %} + +Download [this zip](http://filebin.ca/3AZSHoXPnbEv/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: + intents: + 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(' ', '_') }}" +``` + +[apiai-web]: https://api.ai/ +[templates]: /topics/templating/ diff --git a/source/images/supported_brands/apiai.png b/source/images/supported_brands/apiai.png new file mode 100644 index 0000000000000000000000000000000000000000..735bd31fd6f7473204ec931c95aba916e8af02dd GIT binary patch literal 3062 zcmVPx=ut`KgRCodHTMKYh)fxWJ-OYw2BqTvZd7B4$EY7q_3l&jurUk51ri@@`iikx5 zNdO%>g@l)Z@|5v0Py>WVnHFahOWU!C)xr=NMeRW2fO$Z&k(dw&E$>QRyZ7&Rvf1R` zyYEdlpv^yXa_{+H=kcHOpa1-OL(~PZ&rKgyk)4*-1r@!bVa$LCLx${G>GzY_v_S~^ zsg!5tQbB5dQenm4!qL|&6WR=fWHfu0ZMcY1*AR(kP!wZRFy6;Z>e7_LisMFFZ@v3w zASk1i&aow0qdA`iEfgf812qrh{ng=cXZJ;x&@1UO}JNwEX3SnB_S&z&c zvtt&KvQV$x{;*%89iKkbI_R$ci?FBiAQ-O~4p3uq5~+Jyn$&{yJ!k3zaNp5n7)>rd z&DqUw!)U*Vbf=k}OX1Nr>f5;(g==uzJ7_BllbLyCZw$qsKT?jOWbiE0(!lmYms6N&9Y}?|>DJcQn zYd5s{omSD|9;@c3jTa{KCLqQ~bi~XxD)Fj)h2{GS;6EeURyQff+43x0M`EWsJ|l$r zP-i_dZ_F)Yh)fgo+K+8*Gnzd&W1}Di{=A| z#!aG|l|l@-;Y*hJ3fytuyE^G=ix7QlWu5s_Kcd8mFvKWSO~6zUUHyj;1EDu^fH7mf zo0D8)5Ei0VJCU_s2*IJWDo$ikRD#*|4P0SVD1zO=>vTFNr*5zKz?Ux9Ae}QX$Q|{0K;L@c@7B=dD;5uLCMsDc#F$ns z4Z2=H9gD>cdNI4Z0jJSmQW)*Z zBgym;c=s_EXyOdzAx)d@?GKJp3UIEZY%5#d=FAG&WIka$)JlI;v}t zR|CuFscgLz~x5|#TY{t3NFsP4SICP7F$ z22>pzg|N5{)~?fW5N&IX27Fso+fMgK4*J@ZjUtt{Su||4QTo`zYXpqMu0C~v^ zj~s(f&>O9t4H*mzUSG7tD!;1E&D?aQ_1fzxg{6Cs&K~*Juo&w?h2g6OC1|zc+&U{* zEKe#d`;)|aK5EsB|ZjexG#}`XDZ4)C_X?)x8w~PgowG| zjo`wujPSHZL!YloUDtif1V>@M8c!7axJ!SV$C6`^JJIX>gU{C(+8XpB76bVugBz z2KeFkK*2=FFgYmDc?K^MUhZyJZ+PJg3ME}D`Y7Eo+_+ajG)$j>=Y5P}vsVruNORpF zhZqs;A`p~@>P2QK^L+_!x{~^5US3n5C9tub{W0iig6%-syivf zeND`bn6v26j5f3Z;ivSjp@0zMu#65rcz5Ovg!EQd3JjQTfc8*%ia}K|QTZexY%K=7 z(Xa-xu^J~`Euu9&;8H#mn8);3nOf=!C{G)tv9nqyAm}OA<4u7)fSw&S#RC%pLY{dp zgM}azkhP!Otp>L(e{}RP7}#`yLqN?K?lv63x=C`SjiNVsX|p&8h5lIJ;&p(XWi*(i zD?iY21yM0fP7o52XK{LI0+E~^kRp<2S*Sq@c2wLk$i560RfY*e6sJ53J(Km?WtO64 zj{)bk3KzW!1Wo_cV@UiS0nT9%(D1k@uC$x7+`t#GdIuV9!x>!BZldSN47foo!9<_K zMAu=G$DsTS6j{Q7(UAWGiXU0tDunebKMWd@Sc!^e9@~CFfYJB_JOTRJ0b^m{JlGQM z*@W{`Uf#uAP~$o{f_(AU^B`4pFPjhrSmpe-LF;f#G6rk@0?%Ebg=4TL=-qA5>#bT$ zR4;ReT?BPM6gc%tWV%Xb{FQfMuwR1~vcaUj+iEmLuwhW{AyzNI8^U3~a0N#Ay1D4_|0-PqA^5d@$$z>P3WpN zpzamgf83NA{8zDSp8!)5iadLuv-w^8vJLm^4fr^ksMS!gTRPwf-ZbZx{1w~-f2FK=AOCoS?L2Tv8EM*coE!P5oQ@8gQq%N9NyXjPG`6uS0dLO51++yj!OC8JQW-q+h~pfcfw2P?xyB z1qoA2uUH5(5WdlvOYoc8Z;}hkzMwYM6#Ox$}e=*&b<52&|2%?$MZQ=n!tZu9H^05c!bRp~LN>;M1&07*qoM6N<$ Ef-!r)VgLXD literal 0 HcmV?d00001