Developers

SDK Setup

Important

Make sure that you have all your credentials and necessary assets available before you start.

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.

Note

All examples shown are set in a Production environment.

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>
Important

Please keep in mind that Inbenta APIs accept HTTPS requests only. If you need to send API requests using other protocols, the only way to do this is to set up a proxy to convert those protocols to the HTTPS protocol before the requests reach the API.

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.

Important

• For best security and performance, Inbenta recommends that you store these files on your own server.

• If you decide to use Inbenta-hosted SDK files, Inbenta strongly recommends that you use a MAJOR.MINOR.PATCH version, as well as SDK Subresource Integrity for additional security for your website.

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.

Note

An SRI check is available for this SDK. For more information, see the SDK Subresource Integrity page. Remember that SRI only works with full versions.

Authorization and build:

Note

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

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:

alt text

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.

Important

• The SDK modifies the HTML class to add `browserDetection` to ensures that the styles are correctly displayed in different browsers.

• In the responsive version, while the Chatbot is open, the `inbenta-chat-open` class is added in the body. This is used to avoid double scrolling while the chatbot window is open.

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:
Matches Data logged
single match CLICK + Content ID of matched content
multiple, user selects one CLICK + Content ID of clicked content
multiple, non-clickable Automatic CLICK + Content ID of each matched content
  • 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+
Caution

If and only if you need server-side authorization, you may use the following `build` method with previous server-side authorization.

Inbenta strongly recommends that you use the more recent buildWithDomainCredentials method described above, since it uses new features and sends fewer requests to the API. createFromDomainKey is DEPRECATED because it performs an authorization for every user even if they do not interact with the Chatbot.

The createFromDomainKey method is documented here for existing legacy integrations and only as a reference. Do not use this method if you are building a new Chatbot from scratch.

Build

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