How to design your assistant on Voiceflow.

Intent, Entity & Variable Management

An overview on how to create, manage and utilize Intents, Entities and Utterances using the NLU Model Manager in your projects.


As you build out your first conversations, you will quickly realize that there are multiple or combination of utterances your end user will say, in order to achieve the same outcome, location or position/part in your conversation. Anticipating every possible response will lead to a messy canvas, and ultimately a frustrated conversation designer.

As conversations get more complex, it's important to manage your conversation paths in an efficient way.

The key for a great conversational experience is to understand the end-users' intentions and extraction of relevant information from that intention, and any associated/relevant action(s) against that information.

Importance of Managing Conversation Logic

Intent-based conversations are less restricted than solely flow-based or linear-path conversations (which can only follow a set conversational path). They can better adapt to a user changing their mind, for example. This means that they can more easily carry out a wider range of tasks and adapt to changing conversation topics.

Efficient management of user intentions, responses, conversation logic and conversation design leads to non-linear and engaging conversation experience with your end-users. This will require and involve the usage of Intents, Entities and conversational logic such as variables.

Intents vs. Entities

Before we dive deeper into managing your conversation model, it's important to set a baseline understanding of the conversational components and fundamentals that will allow you to build dynamic non-linear conversations.

This can be best explained with a conceptual example: “What cake do I buy for my birthday?”

On analyzing the above statement, we can understand two basic things:

  • The person is interested in buying a cake
  • The occasion is a birthday

The former is the Intent, the latter, an Entity. These are the building blocks for most conversation queries. Now, imagine you run a bakery, you might not just be selling cakes; you might also sell muffins, cookies, breads, and much more. In that case, you would want to add two or more Entities with the Intent of buying.

In the graphic above, we can understand that the user’s intention is to access the weather.

To break it down further, let’s define a few terms.

  • Intent - Intention, or purpose of the user in the conversational flow
  • Entity - A data point or value which you can extract from a conversation (and can be slotted into a category/type)
  • Utterance - The input(s)/response that your end-users provide to your conversational experience

Your conversational interface will derive intents and entities from utterances.

The difference between an Intent and Entity is that the intent is the goal that your user has when they’re sending a message to your conversational experience, while the entity is the modifier that your user makes use of to describe their query.

Alternatively, the Intent is an action that the user wants to perform and the Entity is a keyword that you want to be extracted from the user’s utterance.

Note: You can learn more about the Intent Step here.

Therefore, while developing and designing a flexible and dynamic conversation, user/customer intents and entity recognition is crucial.

Model Manager (NLU Model)

A reminder that NLU (Natural language understanding) is focused on your conversation's ability to understand the human language. The NLU Model (Keyboard-Shortcut M) or Model Manager lets you easily create, view and manage data for your project’s interaction model.

More specifically for your project, the NLU Model is how your conversational experience understands & handles how the user will interact and respond in your experience.

Note: Intents, Entities and Variables created in the Model Manager are available globally within the project.

Before your can process unstructured responses/text (utterances) into actions or outcomes in your conversation, your NLU Model needs to be defined in order to understand the peculiarities of what your user will say.

Tip: NLU refers to how unstructured data is rearranged so that your conversation may “understand” and analyze it.

Managing Intents

As established, Intents are critical factors in conversational experience functionality because it is the conversation's ability to parse intent(s) is what ultimately determines the success of the interaction.

To manage your intents, access the Model Manager in the project’s header or with the keyboard shortcut (M), as shown above. Click on the Intents tab to view your project’s existing Intents.

Creating and Editing Intents and Utterances

To create a New Intent (1) , hit the + icon in the search bar. You’ll see a new intent template that’s ready to be populated.

You can also Bulk Import (2) utterances either via the in-line editor or as a (.csv) file.

Tip: You can include entities in your utterances by using curly brackets. Note that Entities must already exist in your project to be used within imported utterances. This can be done when bulk importing utterances, as well.

Deleting Intents and Utterances

You are able to delete existing intents by access the (...) options menu next to the Intent Name field, and selecting Delete. You can also right-click the desired intent in the Intent menu and select Remove.

Note: Deleting Intents/Entities in the Model Manager that are already being used in your project may result in the conversation flow breaking and/or cause the Intent in your project to disappear or malfunction.

The recommended best practice is to remove all use(s) of the Intent in your project prior to deletion in the Model Manager. This also applies to Entity deletion being used in your Intent Utterances, seen below and the next section.

To delete utterances, hit the '-' icon.

Tip: For the purpose of training your conversation to derive intents and entities from your users’ messages with a greater degree of accuracy, you would need to have a range of different example utterances for each and every intent.

Managing Entities

To view your project’s entities, navigate to the Entities tab in the Model Manager.

Creating Entities

To create a New Entity, hit the + icon in the Search Entities bar. You’ll see a New Entity creation screen that’s ready to be populated.

When creating a new entity, you’ll need to enter:

  • Entity Name - you will notice the curly-braced {} in a colored box populate as you input a name; this will be how you invoke/input the entity in Intent utterances or any other applicable part of your project
  • Entity Type - the type of data the entity is capturing
  • Entity Values - its potential values (available when using Custom Entities)
  • Entity Synonyms (optional) - the alternative slot values/variations of the entity values that can classify the Entity slot
  • Entity Color - this does not affect your end-user experience, it helps organize your Model Manager experience

Entity Type

Entity types indicate the type of data the entity is capturing. Depending on your project-type, you will notice a dropdown of various entity types available for your building experience.

In Voiceflow, there are two ways to categorize entities:

Custom Entities: These are the entities that can be defined by the conversation designer as per their use case.

System-Defined Entities: The system entities are commonly used entities that are pre-defined in the system, dependant on channel/project-type.

Channels like Alexa and Google may have existing-defined Entity types like "FirstName". These channel-specific and/or project-type entities will have thousands of built-in examples - saves you from having to enter thousands of names.

Custom Entities

If there isn't an existing built-in Entity type for your use case, you will have to build a Custom Entity type. When building a Custom Entity type, you will manually or bulk-import the values you want your Entities to be able to capture.

Entity Synonyms

Entity synonyms let you enter variations of what a user could say to incite the value of a particular Entity.

Bulk Import Entities

Similarly to bulk importing Intent utterances, you are also able to bulk-import Entities and its synonyms.

You can also do so by clicking the cloud icon next to the Entity Type. You can also import your data via the in-line editor or as a (.csv) file.

Importing Intents, Entities and Utterances

To kick-start your design process, and maintain consistency between your projects and your production Assistant, you can import your Intent, Entity and Utterance data directly from your NLU.

NLU data imports are currently supported for the following providers, in the format they offer data exports in:

  • Amazon Lex V1 (.json in a .zip)
  • Dialogflow ES (.json in a .zip)
  • IBM Watson (.json)
  • Microsoft LUIS (.json in a .zip)
  • Rasa (.yaml in a .zip)
  • Salesforce Einstein (.csv)
  • Amazon Lex (.json in a .zip)
  • Nuance Mix (.xml)
  • Also we support a generalized format - Voiceflow (.csv) - if you want to map your data and import it from another provider

Import on Project Creation

When you create a new project, you will have the option to seed your project with your NLU data by selecting an import.

After you have selected the Channel and NLU you are working with, you will see a link appear to upload your data. Select your NLU's file export, and it will import the Intents, Entities and Utterances contained within it.

Once the model import is complete, you will notice a toast notification/confirmation of the status of the import, such as the number of intents imported. You will also notice the section under the NLU selection box update with this data, and additional information such as number of entities imported.

Tip: Once project creation is completed & you are taken to the Canvas, navigate to the NLU Manager (shortcut M). You can verify and check that the NLU Model data imported successfully/correctly (ie. Intents, Utterances and/or Entities)

More information on this process can be found under NLU Selection in the Project Creation docs found here.

Managing Variables

Note: For a further breakdown on creating & manipulating variables, navigate to this doc here.

To view your project’s variables, navigate to the Variables tab in the Model Manager.

Creating and Deleting variables

To create a new variable, choose its scope (Global or Flow) and type in a name. Hit enter to create your variable.

To delete an existing variable, simply access the delete option from the Variable’s ellipses menu.

Global vs Flow Variables

Every variable created is by default a global variable, meaning it is accessible project-wide.

However, you can also create locally-scoped variables, called Flow Variables that only persist within a given flow.

Tip: Flow Variables can be useful for variable types like counters which should reset to 0 upon exiting the flow.

Other docs in this section