Entities

An entity is a piece of information the virtual agent picks out of the customer's message, such as a date, an amount or a city, so that the intent's action flow can use it. This article covers the kinds of entity, adding them to an intent and using their values in the flow. It is part of Virtual Agent.

The example on this page gives the weather intent a city entity. When a customer asks "What's the weather like in Istanbul today?", the intent's action flow receives Istanbul and passes it to a weather service.

Kinds of entity

System entities (21): Currency, CurrencyAmount, CurrencyType, Date, DatePeriod, Duration, Email, FinancialNumber, Iban, InclusiveTime, LicensePlate, Month, MonthDate, Number, PhoneNumber, SerialNumber, Tckn, Time, VinNumber, Year, ZeroPaddedNumber.

Two system entities take a parameter:

• SerialNumber takes a Length from 1 to 20.
• PhoneNumber takes a Region: International (the default), Turkey, Dubai, US or Canada.

Adding an entity to an intent

Open the intent and go to its Entities tab. The tab lists the intent's entities with Name, Entity Type, Values and Modified Date. Entity Type shows the kind of entity, for example List.

To attach a system entity, or a custom entity that already exists in this virtual agent, click + Entity.

1. Select entity: Lists this virtual agent's custom entities first, then the system entities.

2. Custom entity: Shown as, for example, city / Custom Entity. An entity that is already attached to this intent is greyed out.

3. System entity: Shown as, for example, Date / System Entity.

Choose an entity and give it a name. Your flow uses that name to read the value. For example, attach Date with the name forecast_date.

📝 Note: A custom entity attached to a second intent is the same entity, not a copy. Editing its values changes them for every intent that uses it.

Creating a custom entity

On the intent's Entities tab, open the caret next to + Entity and choose Add Custom Entity.

1. Name: How the flow refers to the entity.

2. Value Type: List (the default) or Regex.

3. Value box: Type or paste a value and click + Add.

4. Values and Synonyms table: The entity's values, each with its synonyms. A synonym is another way a customer might say the same value. Search entity value filters the table.

5. Download Template, Import, Export: Move list values in and out as a CSV file with the columns Value and Synonym. For a long list, download the template, fill it in and import it.

For the weather example:

1. On the weather intent's Entities tab, choose Add Custom Entity.

2. Enter city as the name and keep List.

3. Add these values and synonyms:

   Value	Synonyms
   Istanbul
   New York	NYC, New York City
   Los Angeles	LA
   San Francisco	SF

4. Save the entity. It is added to the weather intent's entity table.

Regex entities

Choose Regex under Value Type and enter a pattern in Regular Expression to be added. The menu beside the field offers presets: Phone Number, Social Security Number, ZIP Code, ID or tracking number, E-mail, E-mail 2 and E-mail 3. Use + Child regex to add up to 11 more patterns to the same entity. To try your patterns against sample text before you save, use Regex Input Test.

Using entity values in the flow

The intent's action flow reads an entity's value as context.entity.<name>. In the example, that is context.entity.city.

Use the Ask Missing Slot node to make sure the value is there. If the customer's message already contained the entity, the node continues straight on. If not, it asks the customer for it. The weather action runs Ask Missing Slot for city first, then calls the weather service with context.entity.city. See Intent Actions.

⚠️ Warning: An intent's entity values exist only inside that intent's action flow. They are cleared when the action ends and the conversation returns to the Virtual Agent node, so a later node in the main flow finds them empty. To keep a value, copy it into a variable inside the action.

You do not need to train the virtual agent again after adding, editing or removing entities.

Global entities

A global entity belongs to the whole project version rather than to one intent. To define one, go to Project Settings > Global Entity and click + Entity. The page has the same columns as an intent's Entities tab.

A flow reads a global entity's value as context.projectEntity.<name>. The Ask Missing Slot node can ask the customer for a global entity and extract it from the reply.

Limits and naming rules