Skip to main content

NLU - Intents and entities

This page walks through Narratory's NLU (Natural language understanding) capabilities, today largely resting on the shoulders of giants (Dialogflow/Google is used under the hood).

Intents#

Intents is an important concept in building conversational apps and refers to what a user means when he/she says something. For example, both "yes" and "I want ice cream" and "why not" likely means that the user wants to buy an icrecream if the bot just have asked the question "Do you want icecream?". This highlights the fact that intents almost always are context-dependent since a Yes would mean something completely different if the bot asked "Do you hate icecream?" or "Have I seen you before?".

Creating intents is done in a similar fashion to defining turns, you do it on the Intents menu.

Each intent has a number of example phrases - basically different ways users can say the same thing.

It is recommended to supply 5-15 example phrases for each intent to start off. When you start testing your app with users you will also quickly learn what phrases you have to add to your intents.

Entities in intents#

Quite often you want to extract some information from an intent. This is where entities come in handy. For example, if you build a fruit seller bot, you likely need to distinguish between the two utterances "I want a banana" and "I want an apple". This would typically be done with an Order fruit intent which has a Fruit entity. The fruit entity would then consist of a list of fruits, with each fruit possibly having synonyms.

Entities have to be included in the example phrases you give an intent. To do so:

  1. Press the cog icon on the define intent block and drag the entities block to the settings block.
  2. Fetch a new entity block from the toolbox
  3. Name your entity variable and choose what type of entity it is.
  4. Add the entity variable to example phrases. You have to use a special block to group the entity values and the text values together for the system to know which entities and texts that together make up an example phrase.

Using captured entity variables#

The entity variables you create are available to use in the dialog as output, and to pass to APIs. For example, you might want to repeat the value of a captured entity right back to the user. The following two blocks shows an example of this:

First, we define our intent which captures the user's favorite color.

Then, we use it in a bot turn and repeat the color back to the user

Several entities in one intent#

An intent can have several entities and even more than one entity of the same type. For example, if an intent captures users attempts at ordering a flight, the relevant entities are typically a destination, a departure city, number of tickets and so on.

Intents with optional entities#

An entity will be considered mandatory if it is included in ALL example phrases. In the below example, the entity is not mandatory.

Built in entities#

Narratory comes with a set of built-in entities (provided by Dialogflow) that allows you to extract everything from numbers and currencies to cities, music artists, countries and (for some countries) addresses. For a full-list of these entities, see the drop-down menu on the Intents page.

Important: Not all built-in entities are available in all languages. See Dialogflow's list of System entities to learn what entities are available in your selected language.

Wildcard entitites#

A special entity is the built-in entitiy any which captures anything. This could be handy in several cases, for example if you want your backend to parse the answer, if you are capturing content that are hard to parse using intents and entities (such as free text feedback for example) or if a built in entity is not supported in the chosen language.

Try to avoid using more than one any entity in the same example phrase since these entities tend to be "greedy" and capture more than you think they would.

Custom entities#

Commonly you want to define your own entities, which you do on the Entities tab. These entities come in three different types:

  1. Enum entities: these are the most common types of entities and consists of a list of enums. Each enum can have several synonyms.
  2. Composite entities: these are entities that consist of sub-entities in some pattern.
  3. Dynamic entities: these are Enum entities but are populated partly or fully from an API.

Enum entities#

Enum stands for enumeration which essentially means a list. An enum entity is Narratory has a list of Enums, where each Enum has a name and optionally any number of synonyms.

An example showing an enum entity with 3 enums is shown below:

An enum entity has the optional parameter fuzzy matching, allowing you to match miss-typed words. If Fuzzy matching is not used, a match has to be 100% - thus it is recommended to write pluralizations as synonyms - for example "banana" and "bananas".

Composite entities#

Composite entities are entities built up by other entities. This allows you to group entities together, which is commonly important when you are working with lists of entities - for example "I want a red t-shirt and a blue jacket" where "red" and "shirt" belongs together, as well as "blue" and "jacket".

Defining a composite entity is very similar to defining an intent, you have to create instances of each sub-entity you are using and give them parameter names and then define patterns of how the sub-entities will be used to form the composite entity.

An example of using a composite entity is shown here:

Here, two sub-entities are used, of the built-in entity color and the custom entity Vehicle. Each of these are given parameter names which are used in the patterns section to support matching phrases like: "red car", "bike blue" and "green colored MC".

Dynamic entities#

A Dynamic entity is a special type of Enum entity that can be partly or fully populated dynamically through an API. This allows your app to dynamically change the entity definitions in real-time, for example depending on what day it is, what preferences a user has previously picked or what products are currently in stock.

Your entity can optionally have a few "hardcoded" enums defined with blocks which will be joined with any enums returned from the API endpoint provided.

You can choose if your dynamic entity should be refreshed every session (i.e every new interaction with the bot), every turn (i.e every time an intent with the enum entity is active) or every build (i.e every time you build the agent).

An example of a dynamic entity is shown here:

This entity has two products that are always available, and the URL of an API endpoint that provides daily products - refreshed every session.

Setting up an endpoint for a dynamic entity#

To serve your dialog with dynamic data for an entity, you have to provide a publically available endpoint that returns an array of Enums defined in JSON.

Narratory will always pass on the sessionId when Dynamic Entities are called during runtime, allowing you to add some logic related to the session.

You can build your endpoint using any web technology as long as you return a valid JSON array with the following format:

[    {        "name": "Enum name 1",        "alts": [            "Synonym 1",            "Synonym 2"        ]    },     {        "name": "Enum name 2",        "alts": [            "Synonym 1",            "Synonym 2"        ]    }]

This can for example be done using Express, NodeJS and Typescript, like below:

export const todaysSpecialsEndpoint = async (req, res) => {  const { sessionId } = req.body
  // Likely fetch from a DB, maybe personalizing the offering based on the sessionId  const specials: Array<{    name: string    alts: string[]  }> = await fetchSpecialsFromDb(sessiodId)
  res.send(specials)}