Entities Training

Learn how to train the bot to extract structured data from user text input.

Entities help you detect and label specific data in user expressions based on examples you provide to the bot. For example, you can train the bot to detect names (of people, companies, places), recognize a specific pattern (IDs, registration plates) etc.

In the expression “I need to see Dr. Grey on Monday” Dr. Grey and Monday are entities (of type doctor and date).

There are 2 types of entities:

built-in (provided by the NativeChat engine)
developer (defined by a developer)

Built-in entity types

The built-in entity types can be used with a Question step without explicitly training your chatbot how to recognize them.

Date

Use the Date entity type to retrieve date values from a conversation. Note that if you are defining validation for the dates such as a Range validation for minimum and maximum date, the validation will be performed for the parsed entity by NativeChat. For example, if the user inputs “I would like to meet with doctor Burke tomorrow”, NativeChat will identify tomorrow as the correct date and will parse the value validation only e.g. 2017.02.02.

Important: Some user expressions, e.g.: “this weekend”, or “this winter” will be parsed to a Date interval comprising a start Date and an end Date. Use the Test Understanding Console to check if a certain expression is parsed into a Date interval

Date (interval)

When you expect that your users will use expressions that might be parsed into Date intervals you can either have 2 question steps that ask for a Date

{
  "steps": [
    {
      "type": "question",
      "entity": "startDate",
      "entity-type": "Date",
      "messages": [
        "When do you want to go on a holiday?"
      ]
    },
    {
      "type": "question",
      "entity": "endDate",
      "entity-type": "Date",
      "messages": [
        "When do you want to come back?"
      ]
    },
    {
      "type": "message",
      "messages": [
        "{{#if endDate}}You gave an interval starting from {{startDate}} to {{endDate}}{{else}}You gave a single date: {{startDate}}{{/if}}"
      ]
    }
  ]
}

or a single question step that asks for Date and specifies "capture-multiple-values": true:

{
  "steps": [
    {
      "type": "question",
      "entity": "date",
      "entity-type": "Date",
      "capture-multiple-values": true,
      "messages": [
        "When do you want to go on a holiday?"
      ]
    },
    {
      "type": "message",
      "messages": [
        "{{#if date.[1]}}You gave an interval starting from {{date.[0]}} to {{date.[1]}}{{else}}You gave a single date: {{date.[0]}}{{/if}}"
      ]
    }
  ]
}

Important: If your use case only makes sense for a single date and not an interval you can make sure that the bot will work seamlessly if the user uses an expression that parses to a single date and offer the user to choose if the expression parses to a date interval or multiple date values by specifying an ambiguity reaction

Time

Use the Time entity type to retrieve time values from a conversation. Note that if you are defining validation for times such as a Range validation for minimum and maximum time, the validation will be performed for the parsed entity by NativeChat. For example, if the user inputs “I would like to meet with doctor Burke tomorrow at 2 in the afternoon”, NativeChat will identify the correct time and will parse the value validation only e.g. 14:00.

Important: Some user expressions, e.g.: “this evening”, or “this morning” will be parsed to a Time interval comprising a start Time and an end Time. Use the Test Understanding Console to check if a certain expression is parsed into a Time interval

Time (interval)

When you expect that your users will use expressions that might be parsed into Time intervals you can either have 2 question steps that ask for a Time

{
  "steps": [
    {
      "type": "question",
      "entity": "startTime",
      "entity-type": "Time",
      "messages": [
        "When do you want to go to the cinema?"
      ]
    },
    {
      "type": "question",
      "entity": "endTime",
      "entity-type": "Time",
      "messages": [
        "When do you want to come back?"
      ]
    },
    {
      "type": "message",
      "messages": [
        "{{#if endTime}}You gave an interval starting from {{startTime}} to {{endTime}}{{else}}You gave a single point in time: {{startTime}}{{/if}}"
      ]
    }
  ]
}

or a single question step that asks for Time and specifies "capture-multiple-values": true:

{
  "steps": [
    {
      "type": "question",
      "entity": "time",
      "entity-type": "Time",
      "capture-multiple-values": true,
      "messages": [
        "When do you want to go to the cinema?"
      ]
    },
    {
      "type": "message",
      "messages": [
        "{{#if time.[1]}}You gave an interval starting from {{time.[0]}} to {{time.[1]}}{{else}}You gave a single point in time: {{time.[0]}}{{/if}}"
      ]
    }
  ]
}

Important: If your use case only makes sense for a single time point and not an interval you can make sure that the bot will work seamlessly if the user uses an expression that parses to a single point in time and offer the user to choose if the expression parses to a time interval or multiple time values by specifying an ambiguity reaction

Datetime

Use the Datetime entity type to retrieve date and time at the same time. In most cases, it would be better to use Date and Time separately so that the chatbot will be able to understand just the date or the time and then ask for the other. The Datetime value is a javascript date. Once a Datetime entity is understood you can use it in messages using the $date formatter.

Number

Use the Number entity type to retrieve numeric values from a conversation. NativeChat will understand “500” as well as “five hundred” and return an entity with value 500 as an integer.

Text

Use the Text entity type to retrieve free-text input from the user such as a subject of a message or a title.

File

Use the File entity type to receive files from a conversation. Entities of this type are not understood from the message text. They are filled when the user sends a file to the bot. The value of a File entity is an object with the following properties:

url - URL of the received file
labels - array of labels that are automatically attached to every image file using image recognition

{
  "steps": [
    {
      "type": "question",
      "entity": "file",
      "entity-type": "File",
      "entity-display": "{{file.url}}",
      "messages": [
        "Please, upload your photo"
      ]
    },
    {
      "type": "message",
      "messages": [
        "Your file is located at URL {{file}}"
      ]
    }
  ]
}

Confirmation

Use the Confirmation entity type to retrieve a specific user confirmation from the text as Yes/No. The value of Confirmation entity is boolean: true if the user confirms or false if the user declines.

Location

Use the Location entity type to receive locations from a conversation. The value of a Location entity is the location coordinates of the received location. Entities of this type are not understood from the message text. They are filled when the user sends a location to the bot.

The metadata of the location is an object in the following format:

{
  "latitude": 34,
  "longitude": 45
}

and you can configure a simple conversation to collect and display the Location as follow:

{
  "steps": [
    {
      "type": "question",
      "entity": "location",
      "entity-type": "Location",
      "messages": [
        "Could you share your location?"
      ]
    },
    {
      "type": "message",
      "messages": [
        [
          "Test message latitude is {{location.latitude}}",
          "Test message longitude {{location.longitude}}"
        ]
      ]
    }
  ]
}

Conversation

Use the Conversation entity type to retrieve the name of a conversation defined in the Cognitive Flow. Accepted values are existing conversation names that can be recognized by user entering a conversation trigger expression.

In this question step for example, if the user answers with a phrase that will trigger an existing conversation, the chosenConversation entity will be filled with the corresponding conversation name:

{
  "steps": [
    {
      "type": "question",
      "entity": "chosenConversation",
      "entity-type": "Conversation",
      "messages": [
        "You can continue only if you answer with a trigger for existing conversation. Type one:"
      ]
    }
  ]
}

This could be useful for validating that the user will successfully continue to another existing conversation.

Developer Entities

Developer entities can and should be used for anything that’s not covered by the built-in entities, and should contain values you can expect from your users.

The more examples and synonyms you provide for each entity, the more your bot will understand.

Lookup Strategies

The lookup-strategy defines the NLP search strategy, and how should NativeChat understand entities from a conversation with a user.

NativeChat offers several different options for training natural language recognition.

Keyword

Use the keyword lookup strategy if the entity type and its value can be identified by a specific word in the sentence.

You can also add synonyms for each value of the entity. The bot will recognize the entity when it sees either the keyword value itself or any of the synonyms.

For example, funny and sitcom could be synonyms of the entity value comedy (of type Genre).

The main keyword value will be stored in the short-term memory as a value of the entity even if the user used a synonym.

Trait

Use the trait lookup strategy if the entity type and its value cannot be identified by a specific keyword in the sentence. In this case the NLP should be able to understand the meaning of the sentence as a whole. In order for that to happen you should define a set of expressions for each value of the entity.

For example, if the user inputs “I want to visit the capital of Germany” the bot will recognize the capital of Germany as the entity value Berlin (of type City).

The chatbot will store the entity value in the bot memory no matter which expression the user actually used.

Regex

Use the regex lookup strategy if the entity has a distinctive pattern like a car registration number, social security number, etc.

Example:

\\w+([\\.-]?\\w+)*@\\w+([\\.-]?\\w+)*(\\.\\w{2,3})+ for recognizing email address.

Somethings missing or not clear?

Ask a question in our community forums or submit a support ticket.