SDK Configuration

Chatbot SDK build options

The following sections describe all the configuration parameters that are available for the Chatbot SDK, their default values and possible options. You can set the configuration in the second parameter of the SDK build method.

The settings are ordered alphabetically.

Important information

[]: Optional parameter.

example1|example2: The parameter must have one of this values.

example:String : The parameter is String type.

Answers

You can modify the Backstage content attribute that the bot uses to display answers.

  • answerAttributes [String] : Settings used to generate normal messages.
  • sideBubbleAttributes [String] : Settings used to generate normal messages.

  • maxOptions[Number] to set the maximum number of contents that the Chatbot can display(default 3).

  • skipLastCheckQuestion[Boolean] : parameter to disable the feature that automatically show the last intent after a 1 by 1 question. It is set to false by default.
  • maxRelatedContents[Number] Maximum related contents to display when applicable (default 3).

If this answerAttributes or SideBubbleAttributes settings are not defined, the api will assume the default values:

"ANSWER_TEXT" for answerAttributes and "SIDEBUBBLE_TEXT" for sideBubbleAttributes

Example

config = {
  answers:{
      answerAttributes: ['ANSWER_TEXT'],
      sideBubbleAttributes: ['SIDEBUBBLE_TEXT'],
      maxOptions:3,
      maxRelatedContents: 3,
      skipLastCheckQuestion:false

  }
}

These are the default values. If you need to set different dynamic settings, send an object with the new dynamic settings:

config = {
    answers:{
      answerAttributes: ['ExampleAnswer'],
      sideBubbleAttributes: ['ExampleSidebubble'],
      maxOptions:2,
      maxRelatedContents: 2,
      skipLastCheckQuestion:true
    }
}

The result looks like this:
Bot_answers

Answer delay

We can set the delay duration when the Chatbot displays an answer, both in conversationWindow and sideWindow. By default, it is set to 700 milliseconds.
Note: This delay does not apply when the side window appears after you click the "show more" buttons.

config = {
    delayOnAnswer: 500,
}

autoDisplaySideWindow

This setting defines if the sideWindow must be opened automatically when a content with sideWindowInformation is displayed as a ChatbotMessage. The default value is true, if it's set to false, the sideWindow won't be displayed unless the user clicks on the more info button.

config = {
    autoDisplaySideWindow: true
}

Avatar

This setting displays an avatar in the conversationWindow.

Caution: An avatar can only be shown on devices with a screen width larger than 768px.

You can find Inbenta's avatar catalog at the following address: https://www.inbenta.com/en/avatar-catalog/

To use an avatar in the Chatbot SDK, edit the following parameters in the build:

  • displayImage:[String]: If you enter a URL in the displayImage attribute, the avatar videos are not displayed. An image is displayed instead. The recommended minimum size for this image is 250x380.

  • displayPosition: "top"|"default": This setting defines the position of the avatar in the chatbot SDK. By default, if the setting is not defined, or if you use any other value than "top", the avatar is displayed to the left of the conversation window. The recommended view when using the "default" display position is "PA Camera".

  • name [String] : This setting defines a name for the Chatbot. In the sample images, it is 'InbentaSDK'. This parameter is empty by default.

  • shouldUse Boolean : Use this setting to allow the avatar to display. When it is set to true, it starts to render the avatar videos when the conversationWindow opens.

  • fallbackImage[String]: Image to be shown for incompatible browsers.

default_avatar

If you use "top", the avatar is displayed to the top of the conversation window. The recommended views for the "top" displayPosition are PC, PMC and PM.

top_avatar

Example

config = {
  avatar : {
    name : '',
    displayPosition:"top",
    displayImage:'<example_url>', // If you enter a URL in the `displayImage` attribute, the avatar videos are not displayed. An image is displayed instead. The recommended minimum size for this image is 250x380.
    shouldUse : true, // only set to true if you have avatar videos or image to show
    videos : {
       // video link played when avatar appears for the first time
       enter : [],
       // video link played when avatar is leaving
       exit  : [],
       // video link played when avatar is waiting a user action
       idle : [],
       // video link played when avatar say something
       speak : [],
    },
    // Image to be shown for incompatible browsers
    fallbackImage : ''
  }
}

Chatbot identifier

This configuration identifies each of the different Chatbot SDKs that may exist in a given subdomain. It is recommended to use a unique identifier (which can be anything you want): This way, if a user goes from a Chatbot in a subdomain to another Chatbot in another subdomain, the configurations and the conversation history will remain unique for each Chatbot.

If none is defined, it uses InbentaBot by default.

Caution: Inbenta recommends that you set unique identifiers if you use several Chatbots across your domain and subdomains (See example below).

Example Suppose you have two different Chatbots in different parts of your website. One integration in the main page, and another, with different configurations and adapters, in your support page. If you define a different chatbotId for each one, users can start new conversations with either Chatbot and both will work properly with their respective configuration. However, if both Chatbots use the same default chatbotId, this can cause problems and the configurations (and conversations) may become mixed up.

config = {
    chatbotId:'InbentaMain' 
};
config = {
    chatbotId:'InbentaSupport' 
};

Show Close button

By default, the conversationWindow hides the "close conversation" button if no HTML was modified. To display this button, set the following configuration to true(default is false):

config = {
  closeButton:{
    visible:false
  },
}

When you click the button, a modal systemMessage appears to request a confirmation. If you confirm that you want to leave the conversation, it triggers a resetSession action that resets the conversation and closes the conversationWindow.

Bot_answers

conversationWindow position

By default, the initial position of the conversation window is in the bottom-right corner of the page. You can change this with the following parameter:

config = {
  conversationWindow: {
    position: {
      top: null,
      left: null,
      bottom: 15,
      right: 15,
    },
  }

The values above are the default values. Change any or all of the four attributes to your preferred values to place the window accordingly.

Custom HTML

You can use the following configuration to modify the HTML in some components. Here is an example of a custom icon created in conversation-window-header.

    config.html = {
        'conversation-window-header':
            '<div class="inbenta-bot__chat__header">'
                +'<div class="header__title">'
                    +'<img src="custom_icon" style=" width: 30px; margin: 0; margin-right: 15px">'
                    +'SDK Demo'
                +'</div>'
                +'<conversation-window-header-buttons />'
            +'</div>',
    }

custom conversation-window

For more information regarding the custom html, please visit the following section: Main section: custom-html

Environment

This is the working environment of the Chatbot SDK. It is set by default to a production environment.

  • production (default): This environment logs the data for the reports displayed in Inbenta dashboards and retrieves the content/categories published in live.
  • preproduction: This environment does not log any data and retrieves the content/categories published in live.
  • development: This environment does not log any data and retrieves the content/categories published in edit.
config = {
    environment:'production'
};

Forms

If your content contains a form, it starts asking the questions in the form automatically. You can modify this setting.

You can also set how many errors the user is allowed to make while they fill in the form before it triggers an "exit form" action, and whether this displays a message to the user or not.

These are the default values:

  • errorRetries: [Number] this defines the number of tries the user has to complete a question before the system asks to leave the form.

  • allowUserToAbandonForm:[Boolean]: if it is set to false, this will not let the user exit the form until all questions are completed.
forms: {
    errorRetries: 6,
    allowUserToAbandonForm: true
},

Show character counter

When the inputCharacterCounter setting is active, a character counter appears next to the chatbot input field. This counter displays how many remaining characters are left for the user.

The inputCharacterCounterMax setting allows you to set a maximum number of characters. The default and maximum values are 256.

By default, the character counter is not visible.

config = {
  inputCharacterCounter:true,
  inputCharacterCounterMax:90

}

Character_counter

Labels

Components have default labels, but it is possible to change them. Here is a list of available labels:

config = {
  labels: {
      en: {
        'yes' : 'Yes',
        'no' : 'No',
        'generic-error-message' : 'The format of your answer is not valid',
        'enter-question' : 'Enter your question',
        'interface-title' : 'Interface title',
        'guest-name' : 'You',
        'help-question' : 'Do you need help?',
        'thanks' : 'Thanks!',
        'rate-content' : 'Was this answer helpful?',
        'form-message' : 'Please tell us why',
        'submit' : 'Submit',
        'alert-title' : 'OOOOPS...!',
        'alert-message' : 'Something went wrong, please click the button to reload.',
        'alert-button' : 'Try again',
        'agent-joined' : '{agentName} has joined the chat',
        'agent-left' : '{agentName} has left the chat',
        'wait-for-agent' : 'Waiting for an agent...',
        'no-agents' : 'No agent available',
        'close-chat' : 'Do you want to close this chat?<p><div class="confirmation-box__subtitle">You will lose the entire conversation.</p></div>',
        'close-agent' : 'Do you want to leave the conversation with this agent?',
        'chat-closed' : 'Chat closed',
        'download' : 'Download',
        'escalate-chat' : 'Do you want to start a chat with a human agent?',
        'agent-typing': '{agentName} is typing',
        'agents-typing': '{agentName} and {agentName2}  are typing',
        'several-typing': 'Several people are typing'
      }
  }
}

To change the text of labels, you can send an object with new labels. This function updates only the defined labels, and keeps the others unchanged.

config = {
    labels: {
      en: {
          'interface-title': 'New demo title'
      }
    }
}

Labels are available in multiple languages (see list below). For reference, click here to view all the labels in all languages.

Language

This is the language that the bot uses for labels, direct message (e.g. "no results") and multiple options. By default, the language is set to English. The following language are available:

Language Value*
Arabic ar
Catalan ca
Chinese zh
Czech cs
Danish da
Dutch nl
Euskera eu
Finnish fi
French fr
Galician gl
German de
Greek el
Hungarian hu
Indonesian id
Italian it
Japanese ja
Korean ko
Norwegian no
Polish pl
Portuguese pt
Romanian ro
Russian ru
Slovak sk
Spanish es
Swedish sv
Tagalog tl
Thai th
Ukrainian uk
Vietnamese vi

Accepted values are represented by ISO 639-1 code:

config={
    lang:'fr'
}

Launcher text

By default, the launcher only shows an icon. If you want to add text, you need to add the following parameter:

config = {
  launcher: {
    title:"Need Help?"
  },
}

Proactive welcome

The Chatbot is configured so that you automatically receive a welcome message when the conversation window opens for the first time. To disable this behaviour, set the parameter to 'false', like this:

config = {
  proactiveWelcome: false,
}

Rating

At this time, the rating options only shows in the side window if it shows content first.

If you need ratings, and there is no attribute in sideBubbleAttributes, you can add a blank attribute to sideBubbleAttributes to display boxes. This displays ratings in the side window.

Use ``ìd```` parameter to set the ID value of the rating, the label it displays and whether it must show a comment field after the user clicks on the rating (this is usually the case for bad ratings).

For each element of the array, an HTML button will be created in the DOM, in the same order of the array. The first button will have the CSS class inbenta-bot-icon--rating-yes. The other elements will have the CSS class inbenta-bot-icon--rating-no.

Important: Ratings must exist in the Backstage (Settings > Ratings), and the ID must be correct. To show ratings, you must define the following object, as there is no default rating.

config = {
    ratingOptions: [
      {
        id: 1,
        label: 'yes',
        comment: false
      },
      {
        id: 2,
        label: 'no',
        comment: true
      }
    ]
}

response configuration: This is optional. If you define a response attribute inside the ratingOption, the bot displays the response after the user clicks on the rating. If no response was set up, it displays the Thanks label.

customClass optional configuration. If you define a customClassattribute, this class will be added in the rating button.

Here is an example of a rating configuration that displays responses after a rating is given:

config = {
    ratingOptions: [
      {
        id: 1,
        label: 'yes',
        comment: false,
        response: "Thank you!"
      },
      {
        id: 2,
        label: 'no',
        comment: true,
        response: "We are sorry about that.",
        customClass:'custom-inbentaButton'
      }
    ]
}

showRatingWithinMessages [Boolean] Default value: false. Show rating within each Chatbot message in the conversationWindow.

If it's true, ratings will be displayed at the bottom of the chatbotMessage in the conversationWindow.

config = {
  showRatingWithinMessages: true
}

HTML Sanitizer

For security reasons, Inbenta escapes several HTML tags. A whitelist of these HTML tags exists. You can modify this list.

The default whitelist is below. If you do not specify sanitizerOptions in the build configuration, the default value applies:

  allowedTags: ['h1','h2','h3', 'h4', 'h5', 'h6', 'blockquote', 'p', 'a', 'ul', 'ol',
        'nl', 'li', 'b', 'i', 'strong', 'em', 'strike', 'code', 'hr', 'br', 'div',
        'table', 'thead', 'caption', 'tbody', 'tr', 'th', 'td', 'pre','img'],
  allowedAttributes: {
    a: [ 'href', 'name', 'target' ],
    img: [ 'src' ],
    div: ['id']
},

AllowedTags is the list of HTML tags that you can use. AllowedAttributes lists the attributes that you can use in the allowed HTML tags (for example, href in an a tag, or src in an image). HTML classes are blocked by default, but you can add them to the whitelist with the following statement: allowedClasses.

Caution: Any change you make to the default whitelist is strictly at your own risk. Inbenta does not recommend the addition of additional tag and will not accept any responsibility or liability for any issue caused by changes in the default whitelist.

In the following example, we include a additional HTML tag iframes and a test class in the p HTML tag:

config={
  sanitizerOptions : {
    allowedTags: ['h1','h2','h3', 'h4', 'h5', 'h6', 'blockquote', 'p', 'a', 'ul', 'ol',
      'nl', 'li', 'b', 'i', 'strong', 'em', 'strike', 'code', 'hr', 'br', 'div',
      'table', 'thead', 'caption', 'tbody', 'tr', 'th', 'td', 'pre','img','iframe'],
    allowedAttributes: {
      a: [ 'href', 'name', 'target' ],
      iframe:['src'],
      img: [ 'src' ]
    },
    allowedClasses: {
      'p': [ 'test']
    }
  }
}

Show time in the Answer

You can display the date and tie in the answers. It does not show by default.

config = {
    showDateTime: true,
}

Show loader while fulfilling initial requests

Chatbot shows a loader in the customConversationWindow until the first message gets a response from the API. The default value is false.

config = {
  showLoader:true,
}

loader

Skin

Main section: Styles

By default, the Chatbot SDK loads two Cascading Style Sheets (CSS) files, space-cowboy.css for the skin and layout.css loads layout information. If you want to use your own design, Inbenta recommends that you load both files, then change specific styles using our CSS guide.

Caution: Remember that if you modify the structural elements, it will affect how the product is displayed. Inbenta strongly recommends that you leave structural elements unchanged.

If you want to build your own CSS from scratch, you can disable the default skin, which will load the layout.css only:

config = {
    skin: false,
}

User type

If you need to set different user types, you must specify which userType the Chatbot SDK will be using. The default value is 0.

config = {
    userType: 0
};

User info

When enabling this setting, the conversation/ request will add the track of the given user_info. In this example, we will add the browser information of the user.

config = {
  tracking:{
    userInfo:{
      browserInfo:navigator.userAgent
    }
  }
};