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.