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 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. Use a script tag to integrate the Chatbot SDK in a webpage.

<script src="https://sdk.inbenta.io/chatbot/1.16.0/inbenta-chatbot-sdk.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.

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.

Deprecated methods: The build method can be used with previous authorization through the domain key, although it will perform an authorization for every user even though they don't interact with the Chatbot.

Inbenta strongly recommends that you use the more recent buildWithDomainCredentials method, since it uses new features that will save requests to the API.

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

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), you have to do it using the adapters:

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

For advanced customization options, see the Advanced Customization section.

To see available methods and variables, see the API methods and variables 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.4.2
  • axios 0.16.2
  • CORS

The following browsers are supported:

  • IE 11+
  • 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+