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 Chatbot App 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

The input field shows an "Enter" button when you focus on it to type an input:

input_field

Note: The "enter" button might appear offscreen on iOS devices due to the default behavior of the operating system. This is not a bug. If this happens, scroll down or to the side to find the button.

Answer delay

You can set a delay duration when the Chatbot displays an answer in both conversationWindow and sideWindow. When a Chatbot answer is made of multiple messages, these messages are shown at the same time by default. You can change this behaviour so that the messages appear one by one after a specified delay. If the answer also contains a sideWindow, this sidewindow opens after the last message in conversationWindow is shown.

  • delayOnAnswer [Number] : Number of milliseconds of delay (default: 700).
  • delayOnMultipleAnswers [Boolean] : Parameter to enable (true) or disable (false) the delay in each of the messages when the Chatbot answer contains multiple messages (default: false).

Note: This delay does not apply when the side window appears after you click the "show more" buttons.

config = {
    delayOnAnswer: 500,
    delayOnMultipleAnswers: true
}

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.

  • videosWithSound [Boolean] : Setting this parameter to true, will allow the avatar to play the sound of the videos given in the configuration. Default parameter: false

  • 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
    videosWithSound : false,
    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 activity on delay

This configuration defines whether the Chatbot SDK shows activity (three blinking dots) if the request takes longer than the defined value. The default value is 0, which means the SDK does not show activity. The value is defined in milliseconds.

config = {
    showActivityOnDelay: 2000
}

In the example above, Chatbot only shows the activity when the request takes more than two seconds to complete.

Delay_activity

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',
        'see-more' : 'More info',
        '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',
        'chat-ticket' : '{ticketId}',
        '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',
        'choose-option': 'Choose an option',
        'selected-option': 'You have selected {variableLabel}',
        'related-content-title': 'You might also be interested in:',
      }
  }
}

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
English en
Estonian et
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
Turkish tr
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

By default, the rating option only shows in the side window when the Chatbot shows content in that side window.

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 id 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 Chatbot App (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'
      }
    ]
}

By default, the ratings appear in the side window, but the position can be modified with the following configurations:

  • showRatingWithinMessages [Boolean] (Deprecated) Default value: false. Show rating within each Chatbot message in the conversationWindow.
  • ratingPosition ["sideWindow"|"conversationWindow"|"mixed"] Default value: sideWindow. Show ratings in specified window.

It is possible to select between 3 positioning options with the ratingPosition parameter.

  • sideWindow (default): the ratings are always shown in the side window. If the shown intent does not have side window, the ratings will not be shown.
  • conversationWindow: the ratings are always shown within each Chatbot message in the conversation window.
  • mixed: the ratings are shown in the side window. When the intent does not have side window, the ratings are shown within the Chatbot message in the conversation window

Note: Inbenta recommends that you use ratingPosition parameter instead of showRatingWithinMessages. Never use both parameters at the same time.

config = {
  ratingPosition: 'mixed'
}

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,
}

When an answer has related contents, the Chatbot shows an introduction text which users can click on to show the related contents. By default, the Chatbot does not show the related content titles until the user clicks the "expand" button.

You can choose to display these titles automatically under the Chatbot answer, without asking users to to expand the module.

Note: When showing the related contents titles automatically expanded, the user can still collapse the module if needed.

The default value is false.

config = {
  relatedContentsExpand: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,
}

Source

Source identifier (e.g. Facebook, mobile, etc.) used to filter the logs in the Dashboards, the provided info will be attached as a header in the conversation request.

config = {
    source:"test"
};

Target container

The Chatbot SDK is appended in the first HTML element within the document that matches the specified selector or group of selectors. The default value is Body.

The container can use either HTML id or classes. For more information, see querySelector method

config = {
    targetContainer: '#chatbotContainer'
};

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
    }
  }
};