What's an entity?

Entities are keywords that represent a number of synonyms. For instance, the entity sports could refer to or represent the following group of items: "walking", "jogging", "running", "football" and so on. Whenever an entity is referred to, the group which it represents is automatically inserted by the bot. So if a user sends the sentence, "I'm interested in running," the bot invokes the entity sports.

Therefore, when you're creating training phrases for an intent, instead of typing in multiple phrases like so: "I'm interested in walking", "I'm interested in jogging", "I'm interested in running", you can just create one training phrase which will look like the following:

"I'm interested in sports".

Entities can be used both in the context of intents as well as in a Knowledge Base. Just like with training phrases for intents, entities can be used in training phrases for Knowledge Base articles.

Entities are usually one or two words as they represent groups of simple objects.

Built-in entities

The platform automatically detects the entities listed below. Using the NLU Assist tool, you can assign these default entities to user interactions and have the bot populate a slot with the user's input to the question to which the entity was assigned.

  • PERSON - Names of people, persons.

  • ORGANIZATION - Names of institutions.

  • NUMBER - Numbers in a sentence (pure number).

  • MONEY - Numbers with currency ($2000).

  • DURATION - Time periods.

  • SET - Group (example month, week).

  • ORDINAL - A number used in the context of order. 15th, 10th etc are examples.

  • DATE - Date related, Today, Tomorrow or explicit dates such as 03/01/2017.

How entities affect the NLU score

The more entities in a training phrase that match, the higher the score. This can be a powerful way to increase your matching accuracy, but if overused, can lead to a lot of false positives.

You can see from the example below, that having 2 entities match the training phrases causes a 30% jump in score from the single entity matches. So use them for the really key elements of your intent, but don’t overuse.

Using entities

To refresh on using entities with intents, check out the Intents tutorial. For using entities with Knowledge Base articles, review Knowledge Base tutorial.

Can I detect entities using JavaScript?

There is a JS method to detect which entities have been picked up by the NLU called getNamedEntities(); This will return an array of entities for a particular entity name. For example, the following will return an array of toppings found. So in an utterance like "I would like a pizza with pepperoni, sausage and peppers" it would return [pepperoni, sausage, peppers]:

var toppingObjects = botContext.getNamedEntities('toppings');

var toppings = [];

if (toppingObjects != null && toppingObjects.length > 0) {

    for (j = 0; j < toppingObjects.length; j++) {




Can an entity return a different value?

Sometimes you will want an entity match to return a value, say for sending to an API. For example, if you have an entity for "color" with values like red, blue, green, yellow, black but your API is expecting a numeric data values like red: 10, blue: 11, green: 12, yellow: 13, black: 14 how would you create this mapping?

In the Intent Builder, when creating your entities, you can provide data with additional values by adding a "~" between the phrase and the data value like this: red~10, blue~11, etc. When calling the entity you would use the following to get the data value:

var color = botContext.getNamedEntities('colors');

var whichColor = '';

if (color != null && color.length > 0) {

    for (j = 0; j < color.length; j++) {

        whichColor = color[j].getDataValue();



How do I use multiple entities to map to a single value?

Sometimes you need a number of entities to map to a single value. For instance, multiple misspellings or alternative utterances that all mean the same thing. Let’s take an Airport example where we want to detect different ways people might enter names of airports. We can use the data value to be the unifier for these different possible utterances.

Using a similar script to the above color example, which returns the data value, would get you the "LAX" or “DFW” you need.