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

*: Mandatory 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.
• maxOptionsNumber : 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:

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

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).

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.

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.

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.

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 : [],
    },
    // 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.

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.

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.

conversationWindow position

By default, the initial position of the conversation window is in the bottom-right corner of the page and the draggable property is set to true, which means the window can be moved around on the screen. You can change the properties with the following parameter:

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

The values above are the default values. Change any or all of the four position attributes to your preferred values to place the window accordingly. If you want to disable the feature that allows to drag the window across the screen, set the draggable property to false.

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

The configuration parameter htmlType allows you to set the Custom HTML type. There are 2 different types:

• components: This is the default value and it allows you to add internal SDK components in the Custom HTML section.
• html-only: This type only allows you to add your own HTML code.

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 the production environment.

• production (default): This environment logs the data for the reports displayed in Inbenta Dashboard screens when the Production environment setting is selected in the Chatbot instance. It also retrieves intents and folders published to Production.
• preproduction: This environment logs the data for reports displayed in Inbenta Dashboard screens when the Preproduction environment setting is selected in the Chatbot instance. It also retrieves the intents and folders published to Production.
• development: This environment logs the data for the reports displayed in Inbenta Dashboard screens when the Development environment setting is selected in the Chatbot instance. It also retrieves the intents and folders published to Test.

For an overview of what each environment represents in terms of the Chatbot SDK environment, the Dashboards environment and the Knowledge Base Version, please consult the table below:

config = {
    environment:'production'
};

Variable values initialization

This parameter allows you to set different variable values upon starting the conversation.

With this configuration you can set multiple values at once as an array, and specify the name and the value for each variable you want to set.

config = {
  variables: [
    {
      /**
       * Name of the variable to which a value is added. This must be an existing variable from the instance.
       * Example: "color"
       */
      name: string,

      /**
       * Value or array of values to capture in the variable. The value cannot be an empty string.
       * Example: "blue"
       */
      value: string|array
    }
  ],
};

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 displays a message asking the user if they want to continue with the form 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

}

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:',
        'created-ticket': 'Your ticket ID {ticketId} has been successfully created.',
        'failed-created-ticket': 'Could not create a ticket.',
        'search-options': 'Search options',
        'connection-lost': 'Connection lost',
        'connection-restored': 'Connection restored',
        'stay-in-queue': 'Do you want to keep waiting for an agent?',
        'outside-working-hours': 'We apologize for the inconvenience, but our agents are currently unavailable as it is outside of our working hours. Please try again later or leave us a message.',
        'references': 'Answer references',
        'answer-generated-based-on': 'This answer was automatically generated based on the following contents:',
        'learn-more-answer-context': 'Want to know more? Click the link below.',
        'read-more': 'Read the full content here.',
        'read-less': 'Read less',
        'back': 'Back',
        'answer-references': 'Answer References',
        'see-more-ai-answer': 'For answer references, click here.',
        'hide-ai-answer': 'Hide answer references'
      }
  }
}

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:

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.

translate configuration: This is optional and defaults to false. If you set this parameter to true it will use the value of the label and response parameters as Chatbot SDK labels. For example, if the response parameter is set to bad-rating and translate is set to true, the bot will use the value defined for this label in the selected language.

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: "bad-rating",
        translate: true,
        customClass:'custom-inbentaButton'
      }
    ]
}

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

• ratingPosition "sideWindow"|"conversationWindow"|"mixed" : Default value: sideWindow. Show ratings in specified window.

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

You can select one of three 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

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', 's', 'strike', 'code', 'hr', 'br', 'div',
        'table', 'thead', 'caption', 'tbody', 'tr', 'th', 'td', 'pre','img', 'figure', 'span', 'mark'],
  allowedAttributes: {
    a: [ 'href', 'name', 'target' ],
    img: [ 'src', 'alt'],
    div: ['id'],
    td: ['colspan', 'rowspan'],
    '*': ['style', 'class'],
    ol: ['start']
  },
  allowedSchemes: [ 'http', 'https', 'ftp', 'mailto' ],

• 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.
• allowedSchemes is the list of URL schemes that are allowed (for example in href, src attributes)

In the following example, we include an 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', 'figure', 
      'span', 'mark', 'iframe'],
    allowedAttributes: {
      a: [ 'href', 'name', 'target' ],
      iframe:['src'],
      img: [ 'src', 'alt']
      '*': ['style', 'class'],
      ol: ['start']
    },
    allowedClasses: {
      'p': [ 'test']
    }
  }
}

Show time in the Answer

You can display the time in the answers. It does not show by default.

config = {
    showDateTime: true,
}

Show related contents module automatically expanded

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.

The default value is false.

config = {
  relatedContentsExpand:true,
}

Related contents module position

By default, the related contents module appears within the message in the conversation window, but you can use the following configuration to modify its position:

• relatedPosition "conversationWindow"|"sideWindow"|"mixed": Default value: conversationWindow. Show the related contents in the specified window.

There are three possible positions with the relatedPosition parameter.

• conversationWindow (default): always shows the related contents within the Chatbot message in the conversation window.
• sideWindow: always shows the related contents in the side window. If the shown intent does not have side window, the related contents module does not appear.
• mixed: shows the related contents in the side window. When the intent does not have side window, the related contents module appears within the Chatbot message in the conversation window

config = {
  relatedPosition: 'mixed'
}

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

Skin

Main section: Styles

You can change the skin using the skin parameter. There are six skins available:

• space-cowboy: (default) loads the space-cowboy skin using the space-cowboy.css file.
• ocean-flow: loads the ocean-flow skin using the ocean-flow.css file.
• tatooine-sunset: loads the tatooine-sunset skin using the tatooine-sunset.css file.
• imperial-black: loads the imperial-black skin using the imperial-black.css file.
• teth-sunrise: loads the teth-sunrise skin using the teth-sunrise.css file.
• neutral: loads the neutral skin using the neutral.css file.

You can also load the SDK without a skin. To do so, set the skin parameter to false:

• false: only loads the layout.css file. This loads only layout information, without loading any skin.

If you want to use your own design, Inbenta recommends that you load a skin, then change specific styles using the CSS guide.

config = {
    skin: 'ocean-flow',
}

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

Timezone

You can specify the user timezone using the timezone parameter. The parameter should have a valid TZ database name value (example: Europe/London).

config = {
  timezone: 'Europe/London',
};

connectionEntryPoint

This parameter defines the Inbenta API endpoint where the SDK performs the Auth connection. You can select any available endpoint from the ones defined in Regions and Endpoints.

config = {
  connectionEntryPoint: 'https://api-jp.inbenta.io/',
};

Stream

This configuration allows you to enable, disable and customize the streaming mode of the Chatbot SDK. When streaming mode is enabled, the Chatbot will display each response in a sequence of small groups (called chunks) of words, instead of displaying the entire response at once.

This configuration allows the following properties:

• enabled Boolean: Enables or disables streaming mode for the Chatbot SDK.
• charsPerChunk Number: Sets the maximum number of characters displayed in a chunk. If there aren't enough characters to reach the maximum, the remaining characters will be displayed. Defaults to 3 characters per chunk.
• delayOnChunk Number: Sets the time delay in milliseconds before the next chunk is displayed. Defaults to 50 milliseconds between chunks.

Use the charsPerChunk and delayoOnChunk properties to customize how fast messages appear in the SDK.

config = {
  stream: {
    enabled: true,
    charsPerChunk: 3,
    delayOnChunk: 50
  }
};

openAutomatically

Enable this setting if you want the Chatbot to open automatically when a user lands on your web page. If the setting is disabled, users need to click the button to launch the Chatbot.

config = {
    openAutomatically: true // boolean, optional. Default: false
}

Generative AI

This configuration allows you to show a disclaimer with AI-generated messages. It allows the following properties:

• showDisclaimerButton Boolean: When this property is set to true, a clickable Info icon is displayed with each AI-generated message. You can define this icon's behavior using the onClickAIDisclaimerButton description.

config = {
  generativeAI: {
    showDisclaimerButton: true,
  }
};

• context: This property defines whether the Chatbot shows additional information about AI-generated responses it provides. With this configuration, you can set multiple values at once as an array. Allowed parameters are:
  • visible: Defines whether the references used to produce AI-generated answers are displayed with the answers. Default value is true.
  • displayInsideWindow: Defines whether the references for AI-generated answers are displayed in the side window. When set to true, each AI-generated message will include a button users can click to view the references it was based on. Default value is false.
  • displayAnswers: When references are displayed, this property defines whether the content of each reference should be fully displayed or not. When this property is set to true, each reference's title, content and URL (if available) is displayed. When this property is set to false (default), reference titles are displayed as links users can click to open the content, and references without URLs or without a title are not displayed at all.

config = {
  generativeAI: {
    context: {
       visible: true,
       displayInSideWindow: true,
       displayAnswers: false,
    }
  }
};