TS Entities Articles

How to create data source entities

Use data source entities in Bold360 AI to turn your data into smart conversations.

Make sure your widget is set to conversational. Learn more here.
In this example, we have a list of mobile phones and we want to create a bot that recommends users the best mobile devices based on their needs. We are going to set up a data source entity based on this list of mobile phones and then create an article that uses this entity.
  1. Create the list of mobile phones in a CSV file.

    A sample CSV file is attached at the end of this article. Learn more about the different data source options and requirements in this article.

  2. In the AI Console, go to Knowledge > Entities.
  3. Choose (Create Entity).
  4. Select data source entity for entity type.
  5. Provide a name and optionally a description for the entity.

    The entity name can contain letters, numbers and underscores. Spaces are not allowed.

    You can use the description to give the entity a more meaningful name or description that helps you identify it later.

    Example: Name your entity MOBILE_PHONES.

  6. Fill out the Data Source URL field.

    You can select the CSV file from your local computer and upload it to Bold360 AI' secure server or you can upload the file to a file hosting service like OneDrive and enter its URL here.

    Note: If you provide a link to the file's location, make sure it's publicly accessible.
    See What are the data source URL options? for more options.
  7. Set the response type to CSV.
  8. Choose LOAD.

    Result: The properties table is now loaded. Properties are the columns that are available in the data source file.

  9. Fill out the Properties table.

    See What are the property options for data source entities? and How do life cycle options work? to learn more about the options.

    Example:

    You should decide what questions the bot should ask the end users to offer the best possible recommendation about phones. In this example, the bot asks questions about brand, price range, and camera quality.

  10. Optional: Define fallback messages.

    See What are fallback messages? to learn more.

    Example: For this example, we enter Unfortunately, there's no mobile device that matches your preferences. for no results and set up a carousel to be displayed with the image, the brand and model, and the price if there are multiple results based on the customer's responses.

  11. Save your changes.
  12. Now go to Knowledge > Articles.
  13. Create a new article or open an existing one and add the entity in the article's body.

    In the article's body, create the final response of the bot: this is what the bot responds when there is a single mobile device to recommend. The response should use the entity to present the details of the selected mobile device. To insert an entity, you can either choose or enter [[ in the text editor and have a drop-down of all entities displayed. Once you add an entity to the response, the entity is automatically added to the article. You can expand the entity to see the questions that the bot may ask the user and adjust them to fit the article if needed.

    Note: You can drag-and-drop entities in the Article Editor to control the order of the questions in the conversation.

    Example: Intent: I want to buy a mobile phone

    Body: ?

  14. Publish the article.

You can now see the conversation in action in your widget ? just enter I want to buy a mobile phone.

Important: The bot doesn't always ask all the questions we set in the entity. It can automatically identify when there is no need to ask a question, for example, when there is only one possible result left. In addition, the order of the questions might differ as the bot automatically chooses the order based on what it estimates as the fastest way to get to a possible answer.

What are the property options for data source entities?

Property options in Bold360 AI enable you to customize entities.

The options listed here are available in the Properties table of data source entites. Some of them you can find under (More options).

Table 1. Property options for data source entities
Option name Description
Life cycle The Life Cycle field above the properties table sets the life cycle for the entire entity. You can also set a life cycle for each property. Properties can have a life cycle that is shorter than the life cycle of the entity as a whole. For more information about life cycles, see How do life cycle options work?.
Expose? Sets the visibility of this property in a conversation.
Key Displays the header names as they are in the data source.
Name The expression used to identify the property and add to articles. The property name can contain letters, numbers and underscores. Spaces are not allowed.
Detect Controls whether the property is visible in a conversation.
Query The question the bot asks to receive the input from the user.
Life cycle The Life Cycle field of the property sets the life cycle for the specific property. You can also set a life cycle for the entity. Properties can have a life cycle that is shorter than the life cycle of the entity as a whole. For more information about life cycles, see How do life cycle options work?.
Split by A syntax value such as a comma or a vertical bar that is used to separate multiple values in a CSV cell or in the value associated with a JSON key.
Auto Spelling When selected, the customer's answer doesn't have to be an exact match to a value in a CSV cell or a value associated with a JSON key.
Is Shared You can share the selected property with another entity. For example, if you define color in your phone and tablet entities, then you can share the color values across entities. In this case, when the customer selects a phone color that doesn't exist in the phone entity but exists in the tablet entity which is shared, then the bot will know it is a color and present the message defined in the entity for no results.
Autocomplete When selected, customers are offered autocomplete, or type-ahead options as they enter the entity value.
Use Quick Option The customer can choose from the values that a specific CSV column or JSON key contains. For example, if the CSV contains Apple, Samsung, and Google in the Brand column for a list of mobile phones, these options are displayed as buttons to the customer. See How to use quick options in a conversational article to learn more.
Parent property You can set up a dependency between two properties of the same entity. For example, the parent property of Cities can be Country. When the customer is asked about these two properties, the following happens:
  • The bot asks the question for the parent property first. For example, What country are you located in? and then Which city do you reside in?.
  • If the Country property is either asked again or deleted, the City property is also deleted, that is, the child property behaves in the same way as the parent property.

How to create API-based entities

Entities in Bold360 AI enable you to turn your data into smart chatbot conversations.

Note: The steps described in this article require web developer knowledge.

To set up an API-based entity you need a custom entity to collect data from the customer for the API, a data source entity with the API as its data source that uses the custom entity and an article you use these entities in. In this example, we have an API for data about concert tickets and we want to create a bot that the customer can ask about the tickets that they already booked.

  1. Create a custom entity.

    You create this entity to collect the data required for the API. In this example, we're asking for the customer's email address to display their booked concert tickets.

    Example:

    Entity name: TicketDeails

    Entity description: Collect the customer's email address

    Table 1. Property table of TicketDetails
    Name Detect Bot Query ErrorMessage Life Cycle
    Email Email What's your email address? Please enter a valid email address. Persistent
  2. Create a data source entity with the API as its data source.
    1. Choose (Create Entity).
    2. Select custom entity for entity type.
    3. Provide a name and optionally a description for your entity.

      The entity name can contain letters, numbers and underscores. Spaces are not allowed.

      You can use the description to give your entity a more meaningful name or description that helps you identify it later.

      Example:

      Entity Name: TicketsByName

      Entity Description: Get a list of tickets by email address

    4. In the Data Source URL field, enter the URL of the API and add the property of the custom entity you created in Step 1.

      Example: https://api.example.com/v1/tickets/[[TicketDetails.Email]]

      Result: The custom entity is listed as a dependent entity under the Properties Table. See What are dependent entities? to learn more.

    5. Change Response Type to JSON.
    6. Choose LOAD.
    7. On the set parameters samples dialog enter a sample email address and choose LOAD.

      This way the system knows what a valid response looks like.

      Result: The Properties table is automatically filled with the keys that come from the API.

    8. Define display settings.

      Display settings are available for arrays. See What are the display settings for API-based entites? or more information.

    9. Save the entity.
  3. Create an article that uses these entities.
    1. Go to Knowledge > Articles.
    2. Create a new article or open an existing one and add the entity in the article's body.

      Example: Intent: What tickets do I have reserved?

      Body: ?You have the following tickets reserved: [[TicketsByEmail.TicketsByEmail_ARRAY]]

    3. Publish the article.

What property options are available for custom entities?

Property options in Bold360 AI enable you to customize entities.

Table 1. Property options for custom entities
Option name Description
Life cycle The Life Cycle field above the properties table sets the life cycle for the entire entity. You can also set a life cycle for each property. Properties can have a life cycle that is shorter than the life cycle of the entity as a whole. For more information about life cycles, see How do life cycle options work?.
Name The expression used to identify the property and add to articles. The property name can contain letters, numbers and underscores. Spaces are not allowed.
Detect Specifies the type of input expected from the user, like text, date or number. Validation is completed based on the selection here. For example, if email is selected, the user is expected to enter an email address, otherwise they receive an error. If you choose Date, customers can use a calendar to select the date:
Bot Query The question the bot asks to receive the input from the user.
Error Message The error message displayed to the user when they provide an input that is not valid. You can also set the number of times the error message is to be displayed, that is, the number of chances you give the user to provide the correct format. After that the user receives the fallback message. For example, you have a property where Detect is set to Email, the bot query is What's your email address? and the error message is Please provide an email address. which is set to be displayed 3 times. When the user fails to provide an email address for the fourth time, the fallback message or article is displayed if it is set up.
Note: Validation is not possible for text-type properties, so you can't enable error messages for such properties.
Life cycle The Life Cycle field of the property sets the life cycle for the specific property. You can also set a life cycle for the entity. Properties can have a life cycle that is shorter than the life cycle of the entity as a whole. For more information about life cycles, see How do life cycle options work?.

What are dependent entities?

Dependent entities are entities used in other entities.

When you have an entity with an API as data source, you need to set up a custom entity that collects the information from the user and and include this custom entity in the API-based data source entity to pass it on to the API. Dependent entities provide a better understanding of what properties compose the entity.

To add dependent entities, do the following:

  1. In the AI Console, go to Knowledge > Entities.
  2. Select an existing entity or create a new one.
  3. Choose click URL inputs next to Data Source URL.
  4. Add the entity you want to use.

    You can add an entity on the Parameters,Headers or Bodytab, depending on where it's needed. The entity should be added in [[Entity_Name.Property.Name]].

The dependent entities are listed under the Properties Table.

How can I use entities in user search?

What are the display settings for API-based entites?

Display settings are available for arrays in API-based data source entities.

Choose for an array in the Properties table of your API-based data source entity to set up the following options:

  • Display results in a carousel
  • Display results as quick buttons
  • Display a message when there are no results

What are the data source URL options?

Use these options when providing a link to a file or an API link in the Data Source URL field of a data source entity in Bold360 AI.

When creating a data source entity, you can either upload a CSV or a JSON file from your local drive or add a URL to such a file or provide the URL of an API as data source.

Entities support two types of HTTP methods to integrate an external URL: POST and GET. You can select a method from the drop-down next to the Data Source URL field.
The following options are also available for data source URLs:

  • URL inputs which enable you to add header and body content
  • Interval settings where you can set the refresh interval for how often the cached version of the file is to be refreshed
  • Download file to get a local copy of the file

URL Inputs

To integrate an external data source, you may need to use specific parameters, headers or include specific data in the body of the request when you send it to the server that stores the data files.

When you select (URL Inputs), you have the option to add parameters, headers and a body in case of POST requests. It is possible to include another entity as a parameter, in the header and in the body in which case this entity is listed as a dependent entity under the Properties table. See How to create API-based entities to learn more.

Headers

In several cases, POST requests require specific headers to be sent to the server. When testing a POST request, the tool you're using might automatically add certain default headers without even showing them to you. Make sure you add all headers in the entity configuration.

Body

In the body you can add content. The body of an HTTP request supports different formats for sending content. The format you should use depends on what the receiving server expects. In the AI Console, POST requests in entities support raw format only.

What are entities?

Entities in Bold360 AI enable you to turn your data into smart chatbot conversations.

Tip: Check out this video to see entity configuration in action.

Entities serve as a database for the information that the conversational bot needs to answer your customers' questions. You set up an entity with a data source and provide different questions the conversational bot will ask the customer about the same set of data. For example, you have a data source for mobile phones and you want to create a conversational bot that recommends your customers the best mobile devices based on their needs. Your data source contains information about the brand, the model, the price, the screen size and so on of the mobile phones available. In the entity, you can set up questions about these bits of information, like Any specific brand you're looking for? and What is the price range?. The customer answers these questions and the conversational bot provides the best fit or fits based on their answers.

With entities, you can provide a smart conversational experience to your customers:

  • If the customer provides an answer to a question that the conversational bot hasn't asked yet, it won't ask that question. For example, if someone is looking for an iPhone with 64GB memory, the bot will skip the question about memory type and potentially the one about phone type as well.
  • The conversational bot presents the questions in the most effective way to ensure the customer has to provide the least number of answers to find the result. So regardless of the order of the questions in the entity, the conversational bot rearranges the questions in the most logical way.
  • When a question has one answer only, the bot simply skips that question and does not present it to the customer. For example, if there is only one Samsung phone with a 7" screen, the bot doesn't ask the customer about either the camera or the memory of the phone, but displays the result immediately.

Bold360 AI supports the following types of entities:

  • Data source entities where the data comes from
    • a CSV or a JSON file or
    • an external data source through an API
  • Custom entities that you can use
    • to collect information from your customers in an interactive way
    • an auxiliary for API-based data source entities as they help collect the information required for the API and then trigger the API itself

Conversation entity verification

As a content manager, you can create conversations that verify answers that end-users provided and to prevent any typos or other human errors. To do that, create a new step in the process of API-based entities that will do the following:

  • Summarize the data the user has provided
  • Present the data to the user in the widget
  • Enable the user to change the data if needed or to confirm.

How do data source entities work?

Use data source entities in Bold360 AI to turn your data into smart conversations.

Data source entities can be based on a CSV or a JSON file or can retrieve data from an external data source through an API. In terms of the data source, you have the following options:

  • Upload the file from your local drive
  • Upload the file to a file hosting service like OneDrive and add its URL to the entity
  • Specify the URL of an API
See What are the data source URL options? to learn more.

Makes sure the CSV or JSON file you use with entities meet the following requirements:

  • The file is valid, for example, the CSV file contains no unescaped commas. Use a validator tool to check.
  • If you provide a link to the file's location, make sure it's publicly accessible.
  • The file is structured in a way that
    • Each bot query corresponds to a column
    • Each response corresponds to a row or a part of it
    • Columns are divided into two parts: bot queries and answers.
See this article to learn how to set up an entity with a CSV data source.

How to use custom entities

Use custom entities in Bold360 AI to gather information from your customers and use it to offer a personalized experience.

Make sure your widget is set to conversational. Learn more here.

You can also use custom entities as an auxiliary for API-based data source entities as they help collect the information required for the API and then trigger the API itself.

Instead of asking your customers to fill in a form, you can create a conversation to gather information about the customer. For example, you can set up a custom entity that asks for the customer's name and then include their name in articles. Here's how to do that:

  1. In the AI Console, go to Knowledge > Entities.
  2. Choose (Create Entity) in the top right to create a new entity.
  3. Select custom entity for entity type.
  4. Provide a name and optionally a description for your entity.

    The entity name can contain letters, numbers and underscores. Spaces are not allowed.

    You can use the description to give your entity a more meaningful name or description that helps you identify it later.

    Example: Name your entity UserDetails.

  5. Set the life cycle of the entity to Persistent.

    This way, the bot does not forget the user?s first name once they enter one.

    You can also a set a life cycle for the individual properties keeping in mind their life cycle can't be longer than the life cycle of the entire entity. See this article to learn more about how the different life cycle options work.

  6. Fill out the entities table.

    Example:

    Table 1. Property asking for customer's name
    Name Detect Bot Query ErrorMessage Life Cycle
    FirstName Text Hi, I'm your virtual assistant. What's your first name? N/A Persistent
    Note: Since it's not possible to validate text-type custom entity properties, you can't enable error messages for such properties.

    To learn more about the property options for custom entities, see this article.

  7. Save your changes.
  8. Now go to Knowledge > Articles.
  9. Create a new article or open an existing one and add the entity in the article's body.

    Example: Intent: I want to go to Greece for a vacation

    Body: ?Here are our current offers for you, [[UserDetails.FirstName]]:?

    <add options to the article>

  10. Publish the article.

When an article that uses the UserDetails entity is returned as a response, first the entity question is presented then the article is presented with the name they provided. If the conversation continues and the another article with this entity is returned as a response, the bot won't ask the question again, because the customer name is retained for the duration of the session, as defined by the persistent life cycle option.

Announcements

Genesys DX/Bold360 End of Life: January 2024

The Genesys DX (Bold360) platform will end of life on January 31st, 2024. This difficult decision was announced in March, 2023.  

Genesys continues to make a strong commitment to Genesys Cloud, while tightening the portfolio to further accelerate feature growth on the platform. Part of that included bringing over key Genesys DX features to Genesys Cloud CX, such as Knowledge Optimizer that focuses on ease-of-use knowledge management. Digital only licenses for Genesys Cloud were also introduced late last year, which are suitable to those who are not looking for voice capabilities or who need agent seats that only feature support for digital channels. 

Details on the end of life timeline

As of January 31st, 2024, access to Genesys DX product interfaces and customer-deployed components stop to function. Users will no longer be able to log into product interfaces, and all of the boldchat/bold360/nanorep domains will become unavailable for use. If you are curious on what the code on your website related to this might look like and how to remove it, we encourage referencing this post on the DX community

After January 31st, 2024, admins will still be able to get access for an additional 30 days. This period is meant to allow for extracting the necessary data from the platform. Historical data extraction from your account will be available to retrieve by data extraction APIs (Bold360 APIs and Nanorep APIs).