What the heck are Intents, Entities, and WebHooks?
In our latest release, we’ve added the ability to use WebHooks within your bots. This is a mechanism for allowing users to execute logic on their own systems because of an action. By adding a WebHook to an intent, you can send variables from the chat to your API and return a custom response. This is useful for responding with live or dynamic information, such as weather or stock prices. For those of you not needing to trigger external business logic, or connect to external services you can skip the WebHook section in the example below.
To add this functionality to your bot, you will need to create an intent, which specifies variables to recognise and responses to use when you want a user to carry out a specific action. The intent is fulfilled by recognising variables in the user’s messages that belong to the entities in the intent.
Intents are examples of what a user might say in order to achieve a goal or desired outcome. Imagine a user wants to play music on their Echo device, they might say “Alexa, play music by Bonobo” — the intent is to play music. An entity is something that fulfils an intent, so in this case an artist name fulfils the intent of play music and in this case that artist was Bonobo. (Blatant plug of my favourite artist).
Let’s take you through step by step.
To further demonstrate this functionality, we’ll walk through an example of creating an intent, adding a WebHook and linking the entities that should be recognised by the Intent. We’ll create an intent where a user can ask the bot for some basic information about colours, which will extract some specified variables and send this information to an endpoint for a response.
In this case, we would want to recognise “blue” in the message “tell me about the colour blue”. So we will start with creating an entity.
In the menu, choose the entities option and you will be presented with this page:
Give the entity a name, in this case we’ll choose to call it Colour, and click Create Entity.
Using the Add value… edit box, add some values that you want to capture, and then click Save Entity.
Next we need to create the intent to capture the values, so select intents from the menu.
Enter the name of your intent, in this case colours, and click Create Intent.
In this menu, want to do a few things. First, we want to give an example of how the user might trigger the intent. For example, they may say “tell me about the colour blue”. To add this, enter the text into the box under the User Expressions heading, and click Add Expression and you should see your expression appear in a list below the box.
In the Entities section, we want to tell the intent which variables to look for, so click Add entity to add a new entry.
Now in the list box on the left, select your new entity.
When the intent can’t recognise an entity when an intent has been triggered, we prompt the user to clarify. Click click to enter under the prompt column and you will be presented with a dialog, here you can enter the prompt text, such as “which colour would you like to hear about?” and click Add Prompt. This dialog additionally gives you the option of how many times you’d like to prompt the user. When you’re happy with the chosen options, close the dialog.
Now we can add responses. As we’re going to call out to an external API, the text we send back will be used instead of one of our listed responses. Add one to fall back on in the event of a failure from the endpoint. This is also useful in this case if we want to carry out an external task, but don’t necessarily want to respond with any information. We do however want to return information, so let’s put something like “I don’t know anything about that colour.” And click Add Response. You can add multiple responses here, and one will be chosen to display at random.
If you want to remove any items added to these lists, you can delete them by clicking the delete icon on the right hand side of the items box.
With the details of the intent completed, we need to add the endpoint we want to use. This will require you to have an API endpoint that will accept POST requests. Click Active and enter your endpoint address into the text box. Eg. http://www.mywebsite.com/colourwebhook
Once this is complete, go back to the top of the page and click Save Intent. You will need to train your bot again for this intent to be useable.
