Skip to main content


An entity is a unit of the NLU core. It is a sequence of words that share meaning or fall under a common rule. For example, it can be a name, a timestamp, or a location.

You can use either custom or system entities. All enabled entities can be used for script development.

Custom entities

Custom entities are entities that the developer constructs and configures in the entity editor.

Open a project, then select NLU → Entities in the dashboard. You have navigated to the project entities dictionary.

Custom entities tab

Entity settings

Select Create entity and specify the entity name.


Select the recognized button above the entity name to have the entity recognized in the chat. Select this button again to disable recognition.

Let us have a look at how the script works with different settings:

EnabledEntity is recognized in the conversation. The intent referring the entity will be triggered, the slot will be filled, metadata for that entity will appear in the script.
DisabledEntity is not recognized in the conversation. The intent referring the entity will not be triggered, the slot will not be filled, metadata for that entity will not appear in the script.


Select client under the entity name to make its value unique for each client. Select this button again to disable this feature.

Let us have a look at how the script works with different settings:

EnabledEntity values and metadata are unique for each bot client.
Data obtained from clients are filled in via the API or in the chat.
DisabledEntity values and metadata are specified by the bot developer and are common for all the clients of the bot.

Spelling correction

The Spelling correction feature can be used to correct spelling errors in client requests. If this feature is enabled, possible spelling errors are taken into consideration when entities are being recognized.

This feature is only available for projects in Russian and Ukrainian.

Let us have a look at how the script works with different settings:

Correct spelling errorsEntities will be recognized after the system corrects spelling errors using the client dictionary.
Do not correct spelling errorsEntities will be recognized in the original phrase without correcting spelling errors regardless of project settings.

Additional settings

Word normalization

When the Normalize words setting is enabled, all the words contained in the request are normalized before being searched for entities.

Normalization is supported for English, Russian, and Ukrainian only.
Please note that words included in the entity dictionary do not get normalized, no matter what the value of the setting is. This implies that in order to achieve optimal entity recognition results, you should always specify the entity synonyms in their dictionary forms.

By default, the search for entities in client requests is performed in “strict” mode: if an entity name consists of several words, they are all required to be contained in the request one after another.

However, if the Use fuzzy/substring search setting is enabled, the search for entities allows for a greater request diversity:

  • Words comprising the entity name can have unrelated words in between them.
  • Some words comprising the entity name can be omitted altogether.
Consider the following example: a @City entity matches the cities of the world. The record for New York has new york as its only synonym. However, if the entity has fuzzy search turned on, the entity will be found in such requests as york as well as new freaking york.

Intent expansion

The Automatically expand intents setting is best explained by example:

  1. The @agent entity is defined with a number of synonyms, e.g. agent, helper, support.
  2. The /Switch intent is defined and trained on a single phrase, transfer me to an agent.
  3. If the client says transfer me to support, the /Switch intent will be recognized.
This means that if an entity has this setting turned on, then its synonyms contained in intent training phrases are automatically expanded to all words recognized by this entity. This feature makes building the training set for your intents much easier.
This setting is only available for the STS classifier.


An entity is defined via a set of values that it can take. In the dictionary window, select Add record. Select one of the methods for specifying the values:

  • Synonyms — specify the set of synonyms: all the spelling variants which will be equivalent to this value.
  • Pattern — specify the pattern: a formal rule that describes keywords and expressions. Use basic pattern elements.

You can also specify DATA: reference data on the entity, in the string or JSON format.

System entities

System entities are built-in entities that the developer can activate in the entity editor.

You can activate the recognition of system entities. Open a project and select EditorEntitiesSystem entities in the dashboard.

System entities tab

Select the entity name to view its description and recognized formats.

To activate a system entity, enable the checkbox next to its name. As soon as the status is changed, JAICP will start recognizing this entity in the messages sent to the bot.