API Setup

Introduction

Important: Please read this page carefully and make sure that you have all your credentials and necessary assets available before you start. If you need help, contact us.

The purpose of the Chatbot API is to create an interface that is able to communicate with users in natural language to help them with their queries. You can then use this interface and track event data for usage analysis. You can find these reports in the dashboard of the Backstage.

This page describes how to set up the Chatbot API, request and retrieve information.

Obtain Authentication and Authorization Keys

All requests to Inbenta APIs endpoints will be authenticated and authorized.
To obtain your credentials, see Finding your API credentials in the Help Center.

  • The API Key will grant you access to the APIs.
  • The Secret allows the request to access your instance's data.
  • The Domain Key allows the request to access your instance's data, but only for requests coming from the browser (front-side integrations) and from a limited set of domains.

Note: For a complete description of keys and authorization methods, see the Authorization section.

Caution: Your Secret must remain confidential. To prevent third parties from accessing your API, always perform this request in a server-side environment. Never expose your secret in client-side integrations. For more information, see the Authorization page.

Use the access token

You need a valid access token to use Inbenta APIs. Follow the steps listed in the Authorization section to set up your page with your token and refresh it. Once you obtain the access token, you must append it to every request inside the Authorization header, with the format Bearer <your_access_token>.

Get the API URL

The Inbenta API's base URLs depend on the project so we can offer a world wide service and allow service auto-escalation. This base URL may change over time and it should not be persistently stored or cached. Instead, you should get it every time you obtain a new valid access token.

To get the current API URL for your project, there must be a request to https://api.inbenta.io/v1/apis like this:

curl -X GET \
  https://api.inbenta.io/v1/apis \
  -H 'authorization: Bearer <your_access_token>' \
  -H 'x-inbenta-key: <your_API_Key>'

This request will return a response like this:

{
    "apis": {
        "chatbot": "https://endpoint.inbenta.example/prod/chatbot"
    }
}

Caution: Do not perform this request after each API call! You would quickly exceed your rate limits.

Specify the version

Once you have picked the appropriate product URL for your implementation, remember to specify the version of the API.

You specify the version at the end of the URL with v + {version}.

Examples:

The URLs for the current latest version of the Chatbot API look like this:

  • Chatbot: "https://endpoint.inbenta.example/prod/chatbot/v1"

Use the API

Authorization

Note: For a complete description of keys and authorization methods, see the Authorization section.

You need a valid access token to use Inbenta APIs. Follow the steps listed in the Authorization section to set up your page with your token and refresh it.

Caution: Your Secret must remain confidential. To prevent third parties from accessing your API, always perform this request in a server-side environment. Never expose your secret in client-side integrations. 

Start Session

You must create a conversation with the bot before you send messages. Use the API key and the access token to create the conversation. When the conversation is created, you obtain a session token to use as an identifier. Use the access token and the session token to send messages to the bot and keep track of events.

You can configure conversation parameters such as answers or forms. For more information about available parameters, see the "conversation" section of the API routes.

Retrieve information

The bot has four types of answers: answer, polarQuestion, multipleChoiceQuestion and extendedContentsAnswer. For more information about each answer type and forms, see API Answer types.

Variables

The API can store information and use it at a later point in the conversation. This information will be stored as long as the conversation lasts, in variables that you define.

The function of variables is to give the bot extra information, and eliminate redundant requests for information that has already been given. For example, it can store user information such as name or reference number to pre-fill in a form.

Important: The variable name linked to the form field must be the same as the one used to capture the data in the API.

For more information, see the conversation/variables section of the API routes.

Track events

  • For more information on what data Inbenta tracks and how, see the Tracking Events section.
  • Inbenta provides tracking codes for every content shown. For specific information about what each API endpoint tracks by default, see the API Routes section.
  • To improve the accuracy of your analytics, Inbenta recommends tracking as many event types as possible. To see these recommendations per endpoint, see the Chatbot Tracking Guidelines section.