Import Training Definitions

Learn how to bulk update your training data by importing a JSON formatted training definition.

Instead of using the NativeChat UI to enter and update your training data one expression at a time, you can import a JSON training definition with all entities and values at once.

Important: Importing a training definition overwrites all your training data. This means that any data that is not in the definition you import will be deleted permanently.

Import training definitions

Navigate to the Training tab of the bot dashboard.
Click on the Actions button.
Select Import JSON from the drop-down menu.
Paste you training definitions in the text area.
Click on the Import and overwrite training data button.

Below you can find details about all JSON properties that are used to describe the imported data and their possible values.

Example training definition

{
  "entity-definitions": [
      {
      "name": "Conversation",
      "lookup-strategy": "trait",
      "data": [
        {
          "value": "bookDoctor",
          "expressions": [
            "I would like to book an appointment with doctor John Burke",
            "Can I check the schedule of doctor Burke for tomorrow?",
            "Can you book me an appointment with doctor John Burke on Tuesday?",
            "It will be great if I can meet with doctor Burke this week. What's his schedule?",
            "Is there any available slot for today in doctor Burke's schedule?*"
          ]
        },
        {
          "value": "contactOperator",
          "expressions": [
            "Can I talk to an operator?",
            "Would you get me in touch with a human?",
            "It will be great if I can talk to a person."
          ]
        }
      ]
    }
  ]
}

Important: The value of your Conversation type should directly match the conversation name that you define in the Cognitive Flow definition. The bot won’t know which conversation to trigger if the value doesn’t match the conversation name.

Static entity training

To extract structured information using the questions step, you need to define the entity types that your bot can expect in a conversation. The static entity training lets you manually input the values for your entity types.

name

The name of your entity type. Once you set a name for your entity type, you will be able to use this in the Cognitive Flow by setting the entity-type property.

Tip: It’s a best practice to name your entity types with a Pascal case such as Doctor, Location, ContactPhone, and use CamelCase for the cognitive flow entity like a doctor, location, contactPhone in order to easily differentiate between a type and a variable.

lookup-strategy

The lookup-strategy property defines the NLP search strategy, and how should NativeChat understand entities from a conversation with a user. The strategy can be set to either trait or keywords.

trait

Use the trait lookup strategy if the entity type and its value cannot be identified by a specific word in the sentence. The trait strategy is used when the entity type and value cannot be determined by matching a keyword or synonym from the text, but NLP should understand the meaning of the sentence as a whole. You should define a set of expressions for each value that will be used to identify it.

{
  "entity-definitions": [
    {
      "name": "Conversation",
      "lookup-strategy": "trait",
      "data": [
        {
          "value": "bookDoctor",
          "expressions": [
            "I would like to book an appointment with doctor John Burke",
            "Can I check the schedule of doctor Burke for tomorrow?",
            "Can you book me an appointment with doctor John Burke on Tuesday?",
            "It will be great if I can meet with doctor Burke this week. What's his schedule?",
            "Is there any available slot for today in doctor Burke's schedule?",
            "Book a doctor"
          ]
        },
        {
          "value": "contactOperator",
          "expressions": [
            "Can I talk to an operator?",
            "Would you get me in touch with a human?",
            "It will be great if I can talk to a person.",
            "Contact operator"
          ]
        }
      ]
    }
  ]
}

keywords

Use the keywords lookup strategy if the entity can be identified by a specific word in the sentence. You can also add a number of synonyms for each value.

{
  "entity-definitions": [
    {
      "name": "Doctor",
      "lookup-strategy": "keywords",
      "data": [
        {
          "value": "Dr. John Burke",
          "synonyms": [
            "Dr. John Burke",
            "Dr. Burke"
          ],
          "metadata": {
            "Id": "612ca5a5-5622-4bb2-bfd6-9a96a6a62b84",
            "Title": "Dr.",
            "FirstName": "John",
            "LastName": "Burke"
          }
        },
        {
          "value": "Dr. Stan Smith",
          "synonyms": [
            "Dr. Stan Smith",
            "Dr. Smith"
          ],
          "metadata": {
            "Id": "5eda0d52-338d-49ac-8e1f-4041f343e379",
            "Title": "Dr.",
            "FirstName": "Stan",
            "LastName": "Smith"
          }
        },
        {
          "value": "Dr. Ivo Karlovic",
          "synonyms": [
            "Dr. Ivo Karlovic",
            "Dr. Karlovic"
          ],
          "metadata": {
            "Id": "cf91cdb7-0d2d-4996-8fdf-3ad5f43d6478",
            "Title": "Dr.",
            "FirstName": "Ivo",
            "LastName": "Karlovic"
          }
        }
      ]
    }
  ]
}

regex

Use the regex lookup strategy if the entity has a distinctive pattern like a car registration number, social security number, etc. Entity types with regex lookup strategy require a pattern in their data.

{
  "name": "Email",
  "lookup-strategy": "regex",
  "data": {
    "pattern": "\\w+([\\.-]?\\w+)*@\\w+([\\.-]?\\w+)*(\\.\\w{2,3})+"
  }
}

data

The data property contains all values for this specific entity type.

value

The specific value that will be matched. If the metadata property is not set, invoking the entity using the {{entity}} syntax will return the value instead of the metadata.

expressions

For trait entities only - real-world examples of how would your users engage with your bot. The amount of expression varies, but providing an initial set of 10-15 examples is a good start. Once your bot is live, you will be able to train your bot with real examples coming from your users.

synonyms

For keywords entities only - you can define synonyms that will be also identified as the value of the entity.

pattern

For regex entities only - The pattern is a regular expression that will be interpreted using JavaScript’s RegExp class.

metadata (optional)

You can use the metadata to define a value or an object that you might need to retrieve using the {{entity}} syntax. If you haven’t defined metadata, the returned entity will be its value as defined in the training.

Dynamic entity training

The dynamic entity training uses a web service call to automatically train the Natural Language Understanding (NLP).

name

Same as Static Training name.

lookup-strategy

Same as Static Training lookup strategy.

dynamic-data

You have the ability to call a web service and retrieve the values for your entity type without manually defining them. You also have the ability to include multiple synonym-templates that will generate synonyms for your entity type that is handy.

data-source

The data source contains the information required to call a web service to retrieve the entity values.

endpoint

The web service address from which you want to extract the data.

method

The HTTP method - GET, POST.

headers

Optional headers for making the request.

payload

Any payload defined in a JSON format that you would like to send together with the request.

selector

An optional JSONPath expression to extract data from the HTTP response. We recommend you to create your JSONPath expressions using the jsonpath.com.

value-template

The template that will be used to generate the value for each of your entities.

synonym-templates

For keywords entities you can also define a number of synonym templates to generate additional synonyms for the value.

{
  "name": "Doctor",
  "lookup-strategy": "keywords",
  "dynamic-data": {
    "data-source": {
      "endpoint": "http://yourwebsite.com/GetDoctors",
      "method": "GET",
      "headers": {
        "Content-Type": "application/json",
        "Cache-Control": "no-cache"
      },
      "selector": "$.Result[:]",
      "payload": {}
    },
    "value-template": "{{Title}} {{FirstName}} {{LastName}}",
    "synonym-templates": [
      "{{Title}} {{LastName}}",
      "{{LastName}}",
      "{{FirstName}} {{LastName}}"
    ]
  }
}

expression-templates

For trait entities you can define a number of expression templates to generate expressions for the value.

{
  "name": "Questions",
  "lookup-strategy": "trait",
  "dynamic-data": {
    "data-source": {
      "endpoint": "http://yourwebsite.com/GetQuestions",
      "method": "GET",
      "headers": {
        "Content-Type": "application/json",
        "Cache-Control": "no-cache"
      },
      "selector": "$.Result[:]",
      "payload": {}
    },
    "value-template": "{{Question}}",
    "expression-templates": [
      "{{QuestionSample1}}",
      "{{QuestionSample2}}"
    ]
  }
}

data

You can define additional examples for the dynamically generated values. The values from data collection will be merged with the dynamically generated values by their value.

{
  "name": "Doctor",
  "lookup-strategy": "keywords",
  "dynamic-data": {
    "data-source": {
      "endpoint": "http://yourwebsite.com/GetDoctors",
      "method": "GET",
      "headers": {
        "Content-Type": "application/json",
        "Cache-Control": "no-cache"
      },
      "selector": "$.Result[:]",
      "payload": {}
    },
    "value-template": "{{Title}} {{FirstName}} {{LastName}}",
    "synonym-templates": [
      "{{Title}} {{LastName}}",
      "{{LastName}}",
      "{{FirstName}} {{LastName}}"
    ]
  },
  "data": [
    {
      "value": "Dr. John Burke",
      "synonyms": [
        "the Professor"
      ]
    }
  ]
}

Important: For keywords entities the values should define synonyms, while trait entities require expressions.

Question answering

Question answering can be used for small talk or FAQ scenarios where the bot can directly understand the user question or phrase and provide an answer without requiring additional information. For example, when the user says bye, thanks, or What is your name?.

Here is an example of Q&A entity trained to respond to phrases like thanks and bye.

{
  "name": "SmallTalk",
  "lookup-strategy": "QnA",
  "data": [
    {
      "value": "goodbye",
      "expressions": [
        "bye",
        "goodbye",
        "have a nice day",
        "see you",
        "best wishes",
        "best regards",
        "good night"
      ],
      "answers": [
        "Bye!",
        "See you!",
        "Good bye!"
      ]
    },
    {
      "value": "thanks",
      "expressions": [
        "thanks",
        "thanks for the help",
        "thanks a lot",
        "many thanks",
        "thx",
        "you saved my day",
        "I appreciate that"
      ],
      "answers": [
        "Any time :)",
        "Just doing my job!",
        "You're welcome :)"
      ]
    }
  ]
}

name

The name of your entity, it should be unique and descriptive. In this example, the conversation with the bot looks like a small talk and hence the name.

lookup-strategy: QnA

This is what defines the entity as Q&A. All Q&A entities are trained like trait entities.

data

The data property contains all values for this specific entity type.

value

The specific value that will be matched.

expressions

A number of real-world expressions to teach your bot to understand this entity value.

answers

A set of possible answers, the bot will choose one randomly.

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.

Important: Don’t define custom entity-types with name Text, Date, Time, Number, File, Location or Confirmation as these are reserved words.

Text

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

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. 2/2/2017.

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.

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.

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

Important: The file size is limited to 5 MB when using the web channel.

{
  "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 user confirm or false if user decline.

EntitiesConfirmation

EntitiesConfirmation entity type is reserved for internal use in entities-confirmation step and should not be used for other purposes.

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}}"
        ]
      ]
    }
  ]
}

Somethings missing or not clear?

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