ServisBOT Messenger

ServisBOT Messenger is the default engagement adapter for endpoints. When creating an endpoint, unless the engagement adapter is set to something else, the bot will be available through our messenger.

Messenger Bundles

The ServisBOT Messenger can be run with either the regular or optimized bundle.

  • The regular bundle is larger, and does not use lazy-loading. It loads all assets once at the start and that’s it.
  • The optimized bundle is smaller, and uses lazy-loading. It loads an initial chunk of code, then additional chunks are loaded in as needed.

To use the regular bundle:

<script src="https://lightning.production.helium.servismatrixcdn.com/v2/latest/bundle-messenger.js"></script>

To use the optimized bundle:

<script src="https://lightning.production.helium.servismatrixcdn.com/v2/latest/bundle-messenger-optimized.js"></script>

These two bundles also have counterparts without any polyfills. See here for more details.

Asset path resolution

The optimized bundle lazy loads additional .js & .css files during runtime, as required. The URLs of the additional files are based on the src URL of the script:

<script src="https://lightning.production.helium.servismatrixcdn.com/v2/latest/bundle-messenger-optimized.js"></script>

For the above, the root directory for additional files is https://lightning.production.helium.servismatrixcdn.com/v2/latest/.

If the bundle-messenger-optimized.js is downloaded and hosted as part of a custom website bundle, the asset path resolution may break. In these cases, the attribute ignoreScriptSrcPath can be added to the script tag. This tells the messenger to skip the dynamic path resolution - it will instead use the default URL:

<!-- Hosting the messenger bundle as part of the website itself. -->
<!-- Without ignoreScriptSrcPath, the messenger would check '.scripts/' for additional files. -->
<!-- Because the ignoreScriptSrcPath attribute is there, the messenger will check 'https://lightning.production.helium.servismatrixcdn.com/v2/latest/' instead, where the files actually exist. -->
<script src="./scripts/bundle-messenger-optimized.js" ignoreScriptSrcPath></script>

Whitelisting Domains

You can restrict where your messenger can be displayed by providing a set of domains. When developing on a site locally, it might be helpful to add http://localhost/ or http://localhost:3000 depending on your local settings.

Messenger Init Params

When the messenger is launched, it takes a JavaScript object as a parameter for configuration.

When setting these values, take care to avoid passing boolean values as strings:

  displayRoundel: 'false' - This will not work as expected; ‘false’ is a truthy string.
  displayRoundel: false - This works as expected.

If the wrong type is passed, the messenger will continue to use the provided value, and a warning is logged to the console specifying the init param(s).

// Creating the configuration object
const sbConfig = {
  organization: 'servisbot',
  endpoint: 'servisbot-faq',
  sbRegion: 'eu-1',
  context: {},
  debug: false,
  dir: 'ltr',
  textInputDisabled: false,
  displayAvatar: false,
  displayLightbox: false,
  // container: '', Using the default value
  displayHeader: true,
  autoFailover: true,
  defaultOpen: true,
  defaultClosed: false,
  alwaysOpen: false,
  googleApiKey: 'your-api-key-here',
  customerReference: 'botty-faq-testing',
  previewMode: false,
  // sbDiscoveryUrl: '', Using the default value
  messengerPosition: 'right',
  forceMessengerExpanded: false,
  placeholderText: 'Write a message',
  autoStart: false,
}

const sbMessenger = ServisBot.init(sbConfig); // Initializing the messenger with config

Not all init params have to be specified - any optional parameters can be left out to have them use their default values.

Parameter Type Required Default Value Description
endpoint String Yes undefined The endpoint address to target. The endpoint must exist in the same organization as the organization parameter.
organization String Yes undefined The organization to point to.
sbRegion String Yes undefined The ServisBOT region that the organization is in e.g. 'eu-1', 'us-1', 'usscif1', etc.
alwaysOpen Boolean No false Whether to force the messenger to stay open at all times.
autoFailover Boolean No false (unless the feature flag lightning.autoFailover is enabled for the organization) When enabled, the messenger uses the newest version of Lightning runtime (enhanced messenger).
autoStart Boolean No false Whether to begin a conversation immediately, even before the roundel is clicked. When enabled, it skips showing the preview when previewMode=true is set. Enabling this also skips the pre-session view when using enhanced messenger along with defaultOpen=true.
container String No undefined A valid DOM selector e.g. '#messenger-container'. If the selector matches a DOM element, the messenger will be embedded into it.
context Object No {} (Empty object) The context object to start conversations with.
customStyle String No undefined A link to custom CSS styling.
  • Can be either a link to a CDN or an internal file path containing a .CSS file.
  • See this section for more information about customizing messenger styles.
customerReference String No undefined A custom string reference for the conversation. It can be searched in Portal’s conversation history to find conversations that used it. Can also be passed in the context object as customerReference
debug Boolean No false Enables debug mode for developers. Should be disabled for production bots.
defaultClosed Boolean No false Whether to display the messenger as closed by default, even if there is an active conversation.
  • Mutually exclusive with defaultOpen; if both are set to true, both are disabled on messenger startup.
  • Enabling this has no effect if alwaysOpen is enabled; alwaysOpen will take precedence.
defaultOpen Boolean No false Whether to display the messenger as open by default.
  • If autoFailover is true with this enabled, a pre-session ‘Welcome! How can we help?’ splash screen is displayed before a new conversation.
  • Mutually exclusive with defaultClosed; if both are set to true, both are disabled on messenger startup.
dir String No 'ltr' Messenger text direction - can be 'ltr' for left-to-right, or 'rtl' for right-to-left.
displayAvatar Boolean No false Whether to display avatars next to messages.
displayHeader Boolean No true Whether to display the header at the top of the messenger.
displayLightbox Boolean No false When enabled, instead of the usual full screen mobile messenger, mobile users will see a floating messenger window in the center of the screen. The lightbox can be expanded into a full screen mobile view by the user by tapping a button on the messenger header.
displayRoundel Boolean No true Whether to display the messenger roundel, which opens / closes the messenger on click.
displayTextArea Boolean No true Whether to display the text area for user input.
displayWidget Boolean No undefined Deprecated - Use displayRoundel instead.
forceMessengerExpanded Boolean No false When enabled, the messenger expands to full screen when open.
googleApiKey String No undefined The Google API key to use for when a Google map is displayed to the user.
isNative Boolean No false When enabled, the messenger renders in a native fullscreen mode. Recommend to use forceMessengerExpanded for most cases.
messengerPosition String No 'right' Defines on which side of a page the messenger should appear. Can be 'left' or 'right'.
messengerTextAreaEventHandlers Object No {} An object e.g. { onFocus: () => console.log('focused!'), onBlur: () => console.log('unfocused!') } of event handlers for the text area.
placeholderText String No 'Write message' The prompt text to display to the user in the text area.
previewMode Boolean No false Whether to display pre-session welcome messages to the user before they interact with the messenger as floating message bubbles.
regionalEndpoints Object (array) No 
[{ region: ‘venus-<aws-region>.<chosen-sb-region>.servisbot.com }]
 An array of regional endpoints for the latest version of Lightning runtime to use. The default depends on the chosen sbRegion:
  • venus-us-east-1.<chosen-sb-region>.servisbot.com if the sb region is us-1
  • venus-eu-west-1.<chosen-sb-region>.servisbot.com for other sb regions
resetOnLoad Boolean No false When enabled, the messenger will reset its conversation on each page load.
sbDiscoveryUrl String No undefined Setting this overrides the default discovery URL for fetching organization details during a conversation. When not set, the messenger will use the default discovery URL based on the organization’s region.
sbReference String No undefined A custom string reference for a single conversation. When provided, the same conversation is vended each time, allowing for the conversation to continue from a different engagement adapter. Requires using the latest version of Lightning runtime.
textInputDisabled Boolean No false Whether to disable the textarea input by default.
  • Can be re-enabled later by emitting the host notification SB:::UserInputEnabled
  • See here for more info about host notifications.
textarea Object No 
{
  default: {
    maximumMessageLength: 700,
    characterCountThreshold: 650,
  },
  standard: null,
  secureInput: null,
}
 An object containing config for textarea. See below this table for details.
usageApiKey String No undefined, or the default key of your organization if present The API key to use for the latest version of Lightning runtime, overriding the default. This is not required most of the time as your organization likely has a key set already.
version String No '2' Messenger version label.

Messenger Textarea Configuration

The messenger textarea can be configured using a number of init params:

  • displayTextArea - Boolean which globally disables the textarea if false.
  • messengerTextAreaEventHandlers - Object of event handlers for the text area.
  • textarea - Object of targeted options for different textarea types.

The init param textarea has the following format:

{
  default: {}, // Acts as fallback if standard / secureInput are not defined
  standard: {}, // Targets only the the usual textarea
  secureInput: {}, // Targets only the textarea during secure input.
}

Within each of these objects, the following properties can be set:

  • maximumMessageLength: The maximum number of characters allowed to be sent.
  • characterCountThreshold: The number of characters from the limit, at which the character count will be displayed to the user.

If not provided, the default value is used:

{
  default: {
    maximumMessageLength: 700,
    characterCountThreshold: 650,
  },
  standard: null,
  secureInput: null,
}

Example of overwriting the default values for textarea:

const sbConfig = {
  organization: 'servisbot',
  endpoint: 'servisbot-faq',
  sbRegion: 'eu-1',
  context: {},
  textarea: {
    default: {
      maximumMessageLength: 1000,
      characterCountThreshold: 200, // At 200 characters left, '800/1000' will appear by the textarea.
    },
    standard: null, // This can have maximumMessageLength and characterCountThreshold set, but in this case it falls back to default as it is null.
    secureInput: {
      maximumMessageLength: 200,
      characterCountThreshold: 150, // At 150 characters left, '50/200' will appear by the textarea for secure input only.
    }
  }
}

Styling Messenger

Many aspects of our messenger can be changed without any code. Things like the colors for the bot roundel, messenger, and timeline elements and text can be changed. Default bot roundel: BotRoundel

  • Your messenger will inherit the default messenger style from our platform, unless you have something set up in your organization configuration with is available in the organization tab.
  • Your individual endpoints will inherit your organization style setting unless it has explicit styling configured.

The icon in the roundel can be customized by purchasing an add-on. Reach out to your customer success representative to get started.

Basic Messenger Styling

  • Customize a messenger to match your brand, navigate to the “Endpoints” section of this portal.
  • Select the default endpoint or endpoint for the bot you want to style.
    • You can alternatively get to an endpoint page by navigating to your bot’s resource tab and clicking on the settings link of the endpoint’s card.
  • You will then be able to give your messenger a title, subtitle, logo and background image.
    • the Logo’s max height is 34px tall. The logo will stretch to fill a maximum of 140px but it is recommended you keep the logo less than 80px in order to not conflict with other styling. Supported files include JPG, PNG and SVG.
    • The recommended size for the messenger background is 350px wide by 544px tall. Supported files include PNG and JPG
  • By scrolling further down, you will see a preview of messenger and color configurations to the left. You can change the colors of different elements of messenger and see what they look like before saving your changes.
  • To save your changes and apply this design to the selected bots messenger, select the “Save” button found in the bottom right-hand corner.

Internationalization Settings

Just like messenger styles, internalization options can be applied at both the organization level and endpoint level.

Organization internationalization settings can be set on the Organization Settings page in Portal. Endpoint internationalization settings can be set on a specific endpoint’s edit page to override the organization’s defaults.

You can configure a bot’s endpoint to have a localized title, subTitle and a networkMessage. Before configuring the endpoint through portal, you need to pass in context parameter of Messenger Configuration with the lang of your choice (ex: es for Spanish fr for French).

//  ...other messenger configuration options
context: {
  lang: 'es' // To set Spanish
}

Below is an example of internationalization settings scoped to English (en) and Spanish (es):

[
  {
    "en": {
      "title": "ServisBOT",
      "subTitle": "ServisBOT Messenger",
      "networkMessage": "Connection error",
      "presessionTitle": "Welcome",
      "presessionSubTitle": "How can we help?",
      "presessionIcon": "https://static-00.iconduck.com/assets.00/waving-hand-sign-emoji-512x512-lihf6wsv.png",
      "conversationStartText": "Start a conversation",
      "ctaText": "Message us!",
      "reconnectFailedTitle": "Oops! We're having some trouble!",
      "reconnectFailedSubTitle": "We're trying to reconnect or you can reset the conversation and start again!",
      "reconnectCta": "Resume Conversation",
      "reconnectTooltip": "You're offline",
      "presessionWatermarkColor": "#DDD"
    }
  },
  {
    "es": {
      "title": "ServisBOT",
      "subTitle": "ServisBOT en Español",
      "networkMessage": "Mala conexión de red",
      "presessionTitle": "¡Hola!",
      "presessionSubTitle": "¿Cómo estás?",
      "presessionIcon": "https://icon-library.com/images/hand-waving-icon/hand-waving-icon-9.jpg",
      "conversationStartText": "Iniciar una conversación",
      "ctaText": "¡Envíanos un mensaje!",
      "reconnectFailedTitle": "¡Algo salió mal!",
      "reconnectFailedSubTitle": "Nosotros estamos tratando de conectarse",
      "reconnectCta": "Reanudar la conversación",
      "reconnectTooltip": "Estás desconectado",
      "presessionWatermarkColor": "#FA3"
    }
  }
]

Note: The old version of Lightning Runtime supports only the title, subTitle, and networkMessage parameters for a given language. The rest are ignored unless Enhanced Messenger is enabled on the endpoint. Passing an empty value or "" to the networkMessage will not display a subscription message while the bot loads.

Once saved, these settings will be applied when the corresponding language is detected. If no lang is set in context or messenger init params, the messenger will use the user’s browser’s preferred language.

Note: To see the below, you will need:

  • To be using the enhanced messenger (this can be enabled in endpoint config in Portal), more details
  • autoStart messenger init param to be disabled (when enabled, this skips the pre-session welcome view)
  • defaultOpen messenger init param to be enabled
  • lang to be set to the desired language code in context

Internationalization in Messenger (en) Internationalization in Messenger (es)

The view below appears when a user is having trouble connecting mid-conversation. This view can be tested by either turning off your network connection while talking to a bot, or by throttling your network.

Throttling your network can be done in the browser. Example for Chrome (other popular browsers should have very similar steps):

  1. Open developer tools (F12 or right click on the page -> ‘inspect element’)
  2. At the top, click the ‘Network’ tab
  3. There should be a dropdown for network throttling. Set this to ‘offline’.
  4. After testing, change this dropdown back to ‘No throttling’.

Network throttling

Once offline, the view below should appear after ~15 seconds:

Internationalization in Messenger (Reconnect failed) (en) Internationalization in Messenger (Reconnect failed) (es)

Advanced Styling

Custom Styling

Further customization can be done to the messenger using custom CSS. You can do this by initiating messenger with customStyling. Read More

Custom Icons in the Roundel

When custom roundels are enabled for your organization, the endpoints and organization config will have additional fields that can have a custom logo uploaded. SVG format with a square aspect ratio and solid color is recommended.

Accessibility Configuration

Endpoints can be configured with accessibility settings in Portal, available in the endpoint create/edit page as part of Messenger style. The current options are:

Reduce Transparency: When enabled, the messenger renders with less transparency to improve contrast ratios and readability.

Accessibility can also be configured under organization settings in Portal:

  • Your individual endpoints will inherit your organization accessibility setting unless it has been overridden in the endpoint’s configuration.
  • New endpoints will behave the same way as existing endpoints, inheriting the organization settings by default until overridden.

Message Redaction

See here for details on how the ServisBOT V2 Messenger redacts sensitive data from messages: