Api.AI

This component is designed to be used with the “webhook” integration in api.ai. When a conversation ends with a 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 the Internet. api.ai will return fallback answers if your server does 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 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.

Configuring your api.ai account

• Login with your Google account.
• Click on “Create Agent”
• Select name, language (if you are planning to use it with Google Actions check here supported languages) and time zone
• Click “Save”
• Go to “Fulfillment” (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.

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 component.

Examples

Download this zip and load it in your Api.ai agent (Settings -> Export and Import) for examples intents to use with this configuration:

# Example configuration.yaml entry
apiai:

intent_script:
  Temperature:
    speech:
      text: The temperature at home is {{ states('sensor.home_temp') }} degrees
  LocateIntent:
    speech:
      text: >
        {%- 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:
      text: >
        {%- 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:
      text: 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(' ', '_') }}"