Empowering Your Api.ai Assistant with Entities

Here at SitePoint, we've looked at the basics of setting up your own personal assistant using Api.ai and delved further into intents and context. In this article, we'll be going one step further in the process, teaching our assistants completely custom concepts using Api.ai entities.

What is an Entity?

An entity is a concept we want our personal assistant to understand when it is mentioned by the user in conversation. Each entity has a range of values and properties that contain the terms the assistant will need to understand to respond to this concept.

There are three types of entities in Api.ai:

• System - entity types defined by Api.ai such as date, color, email, number and so on which Api.ai already understands. You can find a full list of these entities in Api.ai's documentation on System Entities.
• Developer - Entities which we create for our individual needs — these are what we will be focused on in this article.
• User - These are created for individual users while they use the assistant and can be generated by the Api.ai API to be used within a single session. We won't be covering these in this article but if there's enough reader interest, we might explore this in future!

Api.ai's pre-defined domains (see our very first article on this topic) would be examples of a whole range of pre-built entities that also come with pre-built intents for how to access them. When we add in entities into our assistant, we are adding them to expand into areas that domains do not currently cover and to train our assistant to do something unique to our personal needs.

For example, an entity of "superhero" is not something Api.ai knows about. We could train our assistant to understand a range of superheroes and their various names — "Superman", "Batman", "The Flash", "Green Lantern", "Wonder Woman", "Santa" and so on. It could then understand that these are specific concepts which we want to trigger actions with, such as contacting these heroes when villains strike via an API when we say things like "We need The Flash!".

We also teach our assistant synonyms for each of these so that alongside names like "Superman", it would also understand that Superman is also known as "Kal-El", "The Man of Steel", "Supes" and "Smallville". If we say a different name in the spur of the moment (or someone else tries to request help from our assistant and they call them something else), help from our hero will still come!

While I'd have loved to keep that entity example going for the whole article, I thought it might be best to focus on a more realistic example in the demo itself! In our demo, we will teach our assistant to understand one important metric I get from my Jawbone Up — sleep. The end goal is for our assistant to understand statements like "How many hours of sleep did I get last night?" and "How much deep sleep did I get last night?".

In this article, we will look at the first step of this process — setting up the entities required for our assistant to understand these statements. In a follow up article, we will look at connecting up our assistant web app to third party APIs to give it the information it needs to respond.

Creating a New Entity

To create a new entity, we open the Api.ai console and go to the "Entities" page using the menu on the left. We then create an entity by clicking either "Create Entity", the plus symbol on the "Entities" menu item or the "Create the first one" link which appears for those who have yet to create an entity:

In the page which appears, we enter in our entity name. A common convention is to write this in lowercase with words separated by dashes. We call our new entity "sleep". We leave "Define synonyms" checked and enter one term in the section below it — "sleep". We also can add in synonyms, so we cover a few more options by entering in "rest", "doze" and "shut-eye" next to "sleep". You add each synonym by pressing either the Enter key, Tab key or semicolon (;) key. When done, click Save:

If we return to the "Entities" page, our new entity is shown with the name we will use to access it — @sleep.

Using Our Entity in an Intent

We now need to create a new intent that will train our personal assistant to recognize the sentences which trigger our sleep related requests. We start by heading to the "Intents" page and creating a new intent.

On our new intent page, we include our entity within "User Says" statements like so — @entity-name:alias. In the case of our sleep entity, we call it @sleep:sleep (the second parameter is the alias, which can be used later on as $sleep, however that is a bit beyond the scope of this article). When we include our entity within a user statement like "How many hours of @sleep:sleep did I get last night?", it automatically is added into our parameter section below it:

Above those parameters, we have a field for the action name, this is the name which will be passed to our web app to show what Api.ai thinks the user wants to do. We name our action "sleepHours":

We then can add a variety of different ways to say the same sort of statement, just as we did in the previous article on creating intents:

Continue reading %Empowering Your Api.ai Assistant with Entities%

by Patrick Catanzariti via SitePoint