Entity

Available in Classic and VPC

An entity refers to a dictionary containing registered terms such as personal names, organization names, locations, dates, and product names. Chatbots use entities analyzed from user utterances to discern intent and extract slots. Defining words with the same meaning as an entity helps in understanding user utterances. After creating, modifying, or deleting an entity, you must build or complete the application of changed settings for the changes to be reflected in the chatbot service.

• Types of entities
  • Domain entity: Entities that are frequently used only within a specific domain. They are divided into dictionary-based dictionary entities and regular expression pattern-based pattern entities.
  • System entity: Entities that are commonly available across all domains. They are provided as a built-in feature.
  • API entity: Entities that use entity data stored in an external database without defining entities directly within the Chatbot Builder.

Create domain entities

A domain entity is a collection of key words expected to be used within the relevant domain. For example, when creating a chatbot for coffee orders, you can register and use domain entities, such as the type and size of coffee required for the order.
To register a domain entity:

1. In the NAVER Cloud Platform console, navigate to > Services > AI Services > CLOVA Chatbot > Domain.
2. Click [Run builder] of the domain you want to run the Chatbot Builder.
3. In the Chatbot Builder, click Entity > [Domain Entity] tab.
4. Click [Create Entity].

5. Once you have finished entering the entity information, click [Save].

• Example: Pattern entity
  

• Example: Dictionary entity
  

Create system entities

System entity is an entity that can be used across all domains. NAVER Cloud Platform manages them, and chatbot creators only enable the system entities they wish to use from among those registered.

`@SYSTEM_ANY

`@SYSTEM_ANY is used when you only want to store certain patterns from the user's free utterances. For example, it can be used to analyze entities such as personal names or search keywords that are difficult to define as dictionary entities or pattern entities.

• `@SYSTEM_ANY can only be entered in regular expression questions.
• `@SYSTEM_ANY can match any utterance. It is identical to the wildcard in regular expression syntax.
• We recommend entering other possible patterns in addition to @SYSTEM_ANY, not just registering@SYSTEM_ANY alone.

Regular expression question: What is `@SYSTEM_ANY?

• However, when using optional regular expression patterns as well, matching words to `@SYSTEM_ANY cannot be guaranteed.

Regular expression question: [Describe](give|please) `@SYSTEM_ANY
-> When the user inputs "Describe Clova Chatbot," `@SYSTEM_ANY may match "Clova Chatbot".

• If you only want to register `@SYSTEM_ANY, we recommend setting contexts or conditions to restrict the matching of that conversation to specific points in time.

Regular expression question: `@SYSTEM_ANY
-> When registering a regular expression question that only includes `@SYSTEM_ANY, it may always match the conversation when the user inputs an utterance.

Slot Module

Slot module is an entity that provides the most commonly used entities as shared modules when building quickstart.

• It provides 4 system entities including DATE, TIME, PEOPLE, and NAME. When a utterance containing date, time, number of people, or name is received, it recognizes the patterns for date, time, and number of people within that utterance, stores them in the system entities, and passes the values.
• When using these entities, you can utilize pattern entities such as Date, Time, People, and Name without creating them separately. Instead, you can turn on or off the required entities directly within the system entity.

Slot modules are used to specify user variables in response conditions or to enter user variables in response content.

• To set response conditions, select [User Variables] tab and enter a part of the variable, such as `@DATE, in the [Value] field. A list of slot modules appears.
  

• To enter a user variable in the response, select an entity from the dropdown list of values in the user variable field. When you enter a part of the variable, such as `@DATE, a list appears.
  

DATE

DATE is an entity that recognizes date input patterns, such as "today," "Christmas," "Buddha's Birthday," and "one year from now," and returns the corresponding date.

To use the DATE value within a system entity, turn on the entity to enable it. When the DATE is activated, the TIME Entity is also activated simultaneously.

When handling the date in conversations, you can consider the following two patterns:

• Making a reservation call at a restaurant, etc. -> analyzed : Future date
• Requesting a transaction history from a credit card company -> alternative: Past date

When making a reservation by phone at a restaurant, you typically book a future date. But when requesting a transaction history from a credit card company, you typically review a past date.

The date value has two components, the analyzed and alternative values. This allows you to infer both future and past dates.
For example, if the current date is April 01, 2022, and you say "May 1," it will be analyzed as follows:

• analyzed: 2022-05-01
• alternative: 2021-05-01

Description of analysis values

Example 1: If the current date is May 31, 2022 and the user says "weekend."

Example 2: If the current date is May 02, 2022 and the user says "weekend."

Example 3: If the current date is May 31, 2022 and the user says "today."

Example 4: If the current date is May 31, 2022 and the user says "1."

• Example of an analyzed entity

{
  "literal" : "December 25",
  "analyzed":
  {
    "value" : "2022-12-25",
    "year" : 2022,
    "month" : 12,
    "day" : 25,
    "dayOfWeek" : 5,
    "type" : "availableDate",
    "relative" : 
   {
     "year" : 0,
     "month" : 1,
     "week" : 1,
     "day" : 11
   }
  },
  "alternatives" :
  {
    "value" : "2021-12-25",
    "year" : 2021,
    "month" : 12,
    "day" : 25,
    "dayOfWeek" : 5,
    "type" : "availableDate",
    "relative" : 
   {
     "year" : -1,
     "month" : 1,
     "week" : 1,
     "day" : 11
   }
  }
 }
}

TIME

TIME recognizes input patterns such as "7:30," "2 hours later," and "now," and places the corresponding time into the slot to deliver it.

To activate the TIME, turn on the DATE.

• Example of an analyzed entity

{
  "literal" : "7:30",
  "analyzed":
  {
    "value" : "19:30",
    "hour" : 19,
    "minute" : 30,
    "type" : "availableTime",
    "relative" : 
   {
     "hour" : 1,
    "minute" : 30,
    "second" : -30
   }
  },
  "alternatives" :
  {
    "value" : "07:30",
    "hour" : 7,
    "minute" : 30,
    "type" : "availableTime",
    "relative" : 
   {
     "hour" : 1,
    "minute" : 30,
    "second" : -30
   }
  }
}

People

The People recognizes input patterns such as "1 adult, 2 children" or "3 adults," and delivers the total number of people or the number of adults/children by placing them into slots.
You can turn on the People in the system entity to use it.

• Example of an analyzed entity

{
  "literal" : "2 adults, 1 child",
  "total" : 3,
  "numAdult" : 2,
  "numChild" : 1,
  "type" : "availablePeople"
}

Name

It can recognize names from user-entered values, place them into slots, and export them. 
You can turn on the People in the system entity to use it.

• Example of an analyzed entity

{
  "literal" : "Jung-ah Sunwoo",
  "lastName" : "Sunwoo",
  "firstName" : "Jung-ah",
  "type" : "availableName"
}

How to use

• Store in a user variable: You can select the desired field, such as @{DATE.analyzed.dayOfWeek}, and assign it to a user variable to use.
  

• Task conversation

  • If it is a user response value: You can store it as a literal value and use it.
    

  • If it is a normalized value:
    You can store it as the value of @{DATE.analyzed}, @{TIME.analyzed}, @{PEOPLE.total}, or @{NAME.literal} and use it.
    

• Response

  • You can use the user variables directly.
    

  • If you want to substitute it into a specific format, you can use it by placing it in a user variable.
    e.g., @{TIME:kr.time.partsDay}, is that correct?
    

How to format the response

Create API-integrated entities

API-integrated entities are used when there are entities that cannot be managed within the Chatbot Builder or entities whose information changes in real time. For example, API-integrated entities are used when it is difficult to manage sensitive data such as employee names or customer names by registering them as entities in the Chatbot Builder. By entering the API URL of a server capable of analyzing entities on your behalf, the system can transmit user utterances to that API server for entity analysis, receive the analyzed results, and proceed with the quickstart accordingly.

API-integrated entities are used in the following cases:

• Used as a task slot
• When the entity condition is checked in the response conditions
• When calling the action method v1

To use API-integrated entities:

1. In the NAVER Cloud Platform console, navigate to > Services > AI Services > CLOVA Chatbot > Domain.
2. Click [Run builder] of the domain you want to run the Chatbot Builder.
3. In the Chatbot Builder, click Entity > [API Entity] tab.
4. Click [Edit] in the URL
5. Enter the address of the API that can analyze the entity in the URL, and click [Save].
   • The chatbot makes a call that includes morphological analysis results derived from the provided URL.
6. Click [Create Entity].
7. When the window for creating an entity appears, enter the Entity name, click [Check for Duplicates], then click [Save].
8. Verify the generated entity.

• Request format

{
  "query": "Live in Korea",
  "nlpResult": {
    "data": [
      {
        "words": [
          {
            "in": [
              {
                "morph": "Korea",
                "tag": "NOUN",
                "ner": "Ner=B-Name of the Korea entity",
                "lemma": null,
                "start": 0,
                "end": 5,
                "feature": 0,
                "additionals": ""
              },
              {
                "morph": "Live",
                "tag": "NORMALVERB",
                "ner": "Ner=O",
                "lemma": "Living",
                "start": 6,
                "end": 11,
                "feature": 0,
                "additionals": "in"
              }
            ],
            "word": "Live in Korea"
          }
        ]
      }
    ],
    "success": true
  }
}

• Response format

{
  "code": "OK",
  "message": "Option[String]",
  "entity": [
    {
      "name": "Country",
      "userInput": "Korea",
      "represent": "Korea"
    }
  ]
}

Tag entities manually

Dictionary entities can be tagged in general questions within a conversation. After registering an entity and completing the model build, words corresponding to that entity will be automatically tagged when registering general questions. Tagged entities appear in blue text within the question list of the conversation. Questions tagged with entities are reflected in the training of the conversation model, helping it recognize user utterances.
If the conversation model is not yet built or entities are not automatically tagged, the chatbot creator can tag entities manually.
To tag an entity manually:

1. Complete the preliminary tasks.
   • Add "Pizza Type" entity, representative term: Potato pizza
     
2. After registering your question, drag the words you want to tag as entities.
   • In this quickstart, drag the "Potato pizza."
     
3. When the window for selecting an entity appears, select the Entity you want to tag and click [Apply].
   • You can add it as a new representative term, or add it as a synonym for an already registered representative term.
   • If no entity exists, click [Create Entity] to create a new one.
     
4. Verify that entity tagging has been completed.