Using entities
Last updated
Last updated
Dialogflow entities allow you to send parameter data with your NLP intents to be further processed by Activechat and used in your chatbot skills. This manual describes a simple example of using Dialogflow entities in the Activechat chatbot.
Let’s start by adding another intent to our test Dialogflow agent. Its purpose will be to search e-commerce store inventory by the clothes color. We’ll name it “find_by_color” and it will be used to handle requests like “Do you have something blue?” or “I like white clothes”, with color as a parameter.
Click the plus sign in the “Intents” menu on the left to add another intent. Name it and type “Do you have something blue?” in the “Training phrases” section. Before you press “Enter”, double-click the “blue” word.
A small pop-up will appear with the list of so-called “system entities” provided by Dialogflow. Each of these entities will recognize a specific type of data that can be used in this utterance. Type “color” in the “Filter” field at the top of the list to find @sys.color entity and click it to assign to the word “blue” in the utterance.
Once you do this, Dialogflow will know that there can be any color specified instead of “blue” that you’ve used in the intent definition. Add a couple more training phrases, marking color as an entity. You may notice that sometimes Dialogflow does this automatically for you.
You will notice that the “Action and parameters” section in the intent definition was populated by the new parameter – “color”. It means that Dialogflow will expect a specific color to be included in the intent by the user.
Click “SAVE” and let’s try this intent in the console on the right.
Boom! Even though we’ve used a completely different utterance with a color that is not in the “Training phrases” templates, Google’s AI did the job right – it detected that the intent is “find_by_color” and the user is looking for something that has an orange color. Well done, Dialogflow!
Now let’s see how we can access the value of the intent parameter from within Activechat skill. Go to your chatbot NLP settings (“Bot builder- NLP” in the menu on the left) and click “Refresh intents” to fetch thew updated intent.
You will notice that your new intent appears in the list, and “color” is listed in the “Entities” column. It means that now when this intent will be triggered, you will be able to access the value of that parameter as an attribute. The name will be $_nlp_entity_color (it’s created from the parameter name, prefixed by the $_nlp_entity_).
Let’s display the value in the bot.
When you clicked the “Refresh intents” button, a new skill was created automatically to sync with your new intent. By default, it was using the TEXT block to display Dialogflow response text (from the $_nlp_speech attribute), but we’ve changed this. Now, the bot is responding with “Oh, I love <color_name> too!”, and the <color_name> is the same that was used by the customer in the utterance.
In our simple example, we’re just displaying the parameter value back to the user, but when building an actual chatbot you can use it as a search parameter in your e-commerce blocks, for data processing or external API requests.
Besides the number of pre-defined system entities, the Dialogflow AI engine allows you to use your own custom entities. Let’s build a simple example of a pizza ordering chatbot. We’ll need “order_pizza” intent with “pizza_type” parameter, and this parameter should be a custom entity, containing “Margherita”, “Boscaiola”, “Quattro Formaggi” etc.
Go back to your Dialogflow console and click “Entities” in the menu on the left. The list will be empty when you do this for the first time, so click the blue “Create entity” button in the top right corner.
Give your new entity a name (avoid whitespaces, dots, and dashes, a combination of Latin symbols, underscores and digits will work best) and click the rows to define possible values for the entity.
You should distinguish between the “reference name” and “synonyms”. The synonyms will be used by Dialogflow AI to identify the value of the parameter, but the actual value will be taken from the “reference name” part. In the example above, it means that if the user types “Get me four cheese pizza”, the actual “pizza_type” parameter value sent to Activechat will be “quatro formaggi”, since it’s used as a reference value.
Don’t forget to click “Save” when you’re done with adding different pizza types.
What you do here is define possible options for the “pizza_type” entity, and which utterances can the customer use when meaning each of these options. It helps you streamline possible options to a pre-defined set of values.
Now, let’s add “order_pizza” intent that will use this custom entity. Click the “+” sign in the “Intents” menu, name your new intent and start adding possible utterances as training phrases. For each utterance, double click the part that describes the pizza type and mark it as your new custom entity, typing the name of the entity in the “Filter” field to find it.
As usual, try to add as many utterances as possible to help AI detect correct intent even when customers are using variations of the phrase. Notice that in the “Action and parameters” section there’s a new parameter “pizza_type” now.
Once you do this, you can try your new intent in the Dialogflow console.
Notice that although the utterance is slightly different from the training phrases in the intent definition, the intent was identified correctly and the parameter contains the correct reference value for the pizza type requested by the customer.
Now it should be easy to use this parameter in the Activechat skill. Follow the standard procedure – refresh the list of intents in NLP settings (“Bot builder – NLP” in the menu on the left) to create a new skill for your intent, and add some logic into that skill to achieve the required result. Your new parameter (“pizza_type”) will be available as $_nlp_entity_pizza_type attribute.
And here’s the result on Messenger:
Dialogflow allows you to use multiple entities in a single intent. Here’s a simple example – let’s build an intent to check flight availability from one city to another on a specific date.
The utterance can be something like this: “I want to fly from London to Brussels on Jan 14th”. Let’s build it in Dialogflow!
When adding training phrases for your intent, select the parts that correspond to specific parameters and mark them as entities (either system or custom). You can change parameter names to make it easier to distinguish – in this case, we’ve changed the default names “geo-city” and “geo-city1” with “departure_city” and “destination_city”.
Notice the use of the @sys.date system entity – it allowed us to convert the spoken “Friday” utterance to the specific numbers for date and time. You can find more info in the Dialogflow manuals.
When you connect this intent to your Activechat bot, parameters will be available as $_nlp_entity_departure_city, $_nlp_entity_destination_city, and $_nlp_entity_flight_date, and you’ll be able to use it in your chatbot skill logic.
