The Chatbot SDK uses a javascript call to generate the Inbenta Chatbot. You can set certain configuration parameters to tune it to your specifications.

This page describes how to set up the Chatbot SDK and introduces available configurations and customization options.

Setup

The SDK has two main parts:

• The API which is responsible for holding all the logic related to connecting with the Chatbot API. It is a standalone feature that can be used to implement a custom integration of the Chatbot.
• The UI builder which generates a User Interface (UI) that uses the API client internally and allows for conversation with the Chatbot.

First, you must include the Chatbot SDK in your website. The Chatbot SDK is available in two versions, with or without polyfills. Polyfills transform newer code methods into methods compatible with IE11 browsers by updating the JS prototype objects. The version without polyfills is available from version 1.76.0. Use a script tag to integrate the Chatbot SDK in a webpage. If you need compatibility with IE11 browsers, use the version with polyfills:

<script src="https://sdk.inbenta.io/chatbot/1.16.0/inbenta-chatbot-sdk.js"></script>

If you do not need compatibility with IE11 browsers, you can use the version without polyfills:

<script src="https://sdk.inbenta.io/chatbot/1/inbenta-chatbot-sdk-no-polyfills.js"></script>

Versions

When you set up the SDK for your Inbenta product, you must specify the version, like this:

<script src="https://sdk.inbenta.io/chatbot/<version>/inbenta-chatbot-sdk.js"></script>

Versions are written in MAJOR.MINOR.PATCH format.

If you want to use the Generative AI Chatbot, the minimum recommended Chatbot SDK version is 1.90.1.

Examples

• If only MAJOR is set, this script will use the highest available MINOR version.
  <script src="https://sdk.inbenta.io/chatbot/1/inbenta-chatbot-sdk.js"></script>
• If MAJOR.MINOR are set, this script will use the highest available PATCH version.
  <script src="https://sdk.inbenta.io/chatbot/1.16/inbenta-chatbot-sdk.js"></script>
• If you specify the full version, only this exact version will be used.
  <script src="https://sdk.inbenta.io/chatbot/1.16.0/inbenta-chatbot-sdk.js" integrity="sha384-9K5o2fPlkJx3wfcffW+ufDumZNQL2btDAt1sLicRiDXcVNopNFK+Gnm/k5WU8ytw" crossorigin="anonymous"></script>

Starting from version 1.26.0 (2019.05.15), the SDK automatically logs the version in the user info with two keys. sdk_selected_version logs the version specified in your script (which can be MAJOR, MAJOR.MINOR, or full, depending on your preference). sdk_used_version logs the full version that was actually used. This allows the Dashboards to show the version used in a specific session. To configure the Dashboards, contact your Inbenta representative. This information also appears by default in the new Sessions > Details section.

Authorization and build:

Two methods are available: buildWithDomainCredentials and CreateFromAccessToken.

buildWithDomainCredentials

This method creates the User Interface for the Chatbot SDK. It resolves asynchronously and returns the Chatbot object that contains the API Client. When a user interacts with the SDK (with a click on the launcher), it validates the given credentials to perform the authorization, and starts a new session.

The method performs the authorization, auto-refreshes the accessToken and caches the authorization requests.

var authorization = {   
  domainKey:"<your_domain_key>",   
  inbentaKey:"<your_API_key>"   
}   
InbentaChatbotSDK.buildWithDomainCredentials(authorization);   

CreateFromAccessToken

If you must use the secret instead, you first need to perform a server-side authorization, then call the following method with the provided AccessToken before you generate the UI.

Be aware that when performing the authorization server-side and the build method, the chatbot SDK refreshes the authorization token automatically using the accessToken. If this accessToken expires (e.g. because the computer is in sleep mode, which prevents the SDK from doing the requests), an authorization error appears, and a new server-side authorization is required.

InbentaAuth =  InbentaChatbotSDK.createFromAccessToken(<your_accessToken>,<your_API_key>,<AccessTokenExpiration>);

After you perform the authorization, call the build function. This generates the UI:

InbentaChatbotSDK.build(InbentaAuth)

You can now use the SDK in your website.

Both buildWithDomainCredentials and build have a second, optional parameter, that you can use to set up the configuration of you chatbot SDK. For more information about configuration options, see the Configuration section.

Example:
Here is a basic integration, with no custom configuration. We use the domainKey credentials to use the buildWithDomainCredentials method.

<!DOCTYPE html>
<html>
<head>
 <meta charset="UTF-8">
 <title>Demo</title>
 <script src="https://sdk.inbenta.io/chatbot/1/inbenta-chatbot-sdk.js"></script>
</head>
<body >
</body>
</html>
<script>
var authorization = {
  domainKey:"<your_domain_key>",
  inbentaKey:"<your_API_key>"
}

 InbentaChatbotSDK.buildWithDomainCredentials(authorization);
</script>

The default configuration looks like this:

Go to Integration Example to see an example of a full integration with configuration settings. It also sets a variable using the API Client after the initialization of the Chatbot SDK.

Creating the SDK with an access token

If you create the SDK with an access token, you must call the server before it expires to receive a new access token. (See the Authorization section.)

If the function returns a promise and if it is resolved after you refresh the access token, it will retry the calls made while the token was refreshing. For more information, consult Promises support.

Example

In this example, the AJAX call returns the same access token and expiration as the endpoint does. The response is in JSON format.

sdk.api.setCallbackWhenInvalidAccessToken(function(){
  return new Promise((resolve, reject) => {
    var xhttp = new XMLHttpRequest();
    xhttp.addEventListener( 'load', function() {
      if (this.readyState == 4 && this.status == 200) {
        var object = JSON.parse(this.responseText);
        sdk.api.setAccessToken(object.accessToken, object.expirationAt);
        resolve('success');
      } else {
        reject('error');
      }
    });
    xhttp.open("GET", "?action=getAccesToken", true);
    xhttp.send();
  });
});

Configuration

There are several settings that you can configure. The Integration Example shows a close button, the interface-title, initial position, type of answers, among others.

For more information about configuration options, see the Configuration section.

Styles

If you want to use custom CSS styles, include your own CSS link:

<link rel="stylesheet" href="https://clientwebsite.com/base.css"></script>

For more information about available customization options, see the CSS guide.

Customization

If you want to perform actions using the API client (for example, setting a variable), use the adapters:

function myAdapter(bot) {
  chatbot.subscriptions.onReady(function(next) {
    chatbot.api.addVariable('Name', 'John Doe');
    next();
  })
}

For advanced customization options, see the Advanced Customization section.

To see available methods, refer to the API methods section.

To see available methods that can be used in the API client, as well as a javascript helper to use the API, see the js-client section.

Tracking

The Chatbot SDK relies on the API to track events.

See API Routes for detailed information about tracking events in the API endpoints and how to configure them.

The SDK tracks events directly only in the following conditions:

• In addition to the standard behaviour of the /conversation/message endpoint, if the search returns an extendedContentsAnswer (for example a Federated Bot match from KM or Search), the SDK also triggers a CLICK event. There are several possibilities depending on the number of results and whether or not the results are clickable by the user:

• When a user rates a content, the SDK calls the API to log the RATE event in the non-session log. The logged data includes the content ID, the rate code and the comment if added (optional).

Libraries and Browser Support

The JavaScript SDK depends on:

• vue 2.7.14
• axios 0.26.1
• CORS

The following browsers are supported:

• IE 11+ (only in the Chatbot SDK version with polyfills)
• Last version of self-updating browsers:
  • Chrome
  • Firefox
  • Safari
  • Edge

Supported in WebView mobile applications using:

• Android OS 4.4 KitKat or newer
• iOS 8.0+
• macOS 12.2+

Build

var domainKey = <your_domain_key>
var inbentaKey = <your_API_key>;
var InbentaAuth = InbentaChatbotSDK.createFromDomainKey(your_domain_key,your_API_key);
 InbentaChatbotSDK.build(InbentaAuth);