Recently, one of the colleagues at work introduced api.ai and I was quite intrigued. So I started taking a look and did a small recipe finder bot. I wanted to document the process for others and as well as for my future reference.
- An account in Api.ai (it’s free)
- Heroku Account ( it’s free as well). For hosting our webhook used by the bot.
Some Terminology from Api.ai before we began:
Agents are best described as NLU (Natural Language Understanding) modules. These can be included in your app, product, or service and transforms natural user requests into actionable data.
So an agent is basically the bot itself.
An intent represents a mapping between what a user says and what action should be taken by your software.
Entities are powerful tools used for extracting parameter values from natural language inputs. Any important data you want to get from a user’s request, will have a corresponding entity.
There are 3 types of entities: system (defined by API.AI), developer (defined by a developer), and user (built for each individual end-user in every request) entities. Each of these can be classified as mapping (having reference values), enum (having no reference values), or composite (containing other entities with aliases and returning object type values) entities.
Setting up a webhook allows you to pass information from a matched intent into a web service and get a result from it.
More at the official docs. Have a brief read before you start.
Alright, Let’s start.
Create a new Agent in api.ai:
From the Api.ai console’s left navigation, Choose “Create New Agent”. You can choose to use exisiting google cloud project for this agent or create a new one.
Provide basic info for the agent.
You can leave “Add Sample Data” empty as we would like to build from start.
It will create a welcome and fallback intent for you. So if you write anything in the right pane bot now, it will show a default fallback intent from the available response.
Create Food Entity:
There are many system entities available but Api.ai doesn’t provide food entity ( such as pasta, curry, tea, noodle etc). So let’s create a new Entity.
From the left navigation menu, choose Entities and create a new entity and name it FoodItem. You should provide some example values and synonyms if any. The more synonyms you provide, more robust the BOT can be. Save it.
Go to Intents and Create a new Intent named “Find Recipe”. In the “User Says” area define all the possible sentence you can expect a user to say using the food items defined in out FoodItem entity. For example: “Find me a recipe for curry”, “Recipe for cake” etc. The system will automatically recognize curry and cake from the sentences as our entities.
You would want to provide all the possible way a user could ask the agent to find a recipe. Below is an example for few ways.
A new parameter $FoodItem will be created. This parameter will be passed to our Webhook and we will use it to find recipe use is looking for. You can define more parameters here if need be.
Under the Response Block, Let’s setup a Default Response in case user searches for a food item we haven’t define. For example: “Find me a recipe for Banana Smoothie”.
The $FoodItem parameters will be sent to our Webhook, which will be creating momentarily, For that we need to enable WebHooks for Agent.
Go to Fulfillment from the left navigation bar, and enable Webhook. Save it. We will setup URL for webhook later.
Deploy prebuilt Webhook to Heroku.
I have already built a webhook in Node.js, it receives a post request from our agent with the $FoodItem parameter, finds the recipe using RecipePuppy API and returns the name of the recipe and link to the recipe page. I might write a tutorial about how to create Webhooks for api.ai if time permits.
Head over to my GitHub repo for WebHook and you will find “Deploy to Heroku” button. Go through the deployment process and note down the link to your app. The webhook endpoint would will be [your Heroku app link]/webhook.
Or, If you prefer, you can use the link the app that I already have deployed with this webhook: https://apiapiwebhooksamples.herokuapp.com/webhook
Go back to Fulfilment and provide this new link for URL and Save.
Go back to the intent we created and at the end of the page, there will a fulfilment section, check “Use Webhook” there.
Check out this bot in action: https://bot.api.ai/4122d7bc-fe3a-4e27-82db-0511f6f72734
Recipe Puppy Api
Heroku Node.js documentation