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.

// 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 ServisBotApi = 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 Required Default Value Description
organization Yes n/a The organization to point to.
endpoint Yes n/a The endpoint address to target. The endpoint must exist in the same organization as the organization parameter.
sbRegion Yes n/a The ServisBOT region that the organization is in e.g. 'eu-1', 'us-1', 'usscif1', etc.
context No {} (Empty object) The context object to start conversations with.
debug No false Enables debug mode for developers. Should be disabled for production bots.
dir No 'ltr' Messenger text direction - can be 'ltr' for left-to-right, or 'rtl' for right-to-left.
textInputDisabled No false Whether to disable the messenger text area for the user.
displayAvatar No false Whether to display avatars next to messages.
displayLightbox 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.
container No null A valid DOM selector e.g. '#messenger-container'. If the selector matches a DOM element, the messenger will be embedded into it.
displayHeader No true Whether to display the header at the top of the messenger.
displayRoundel No true Whether to display the messenger roundel, which opens / closes the messenger on click.
autoFailover No false (unless the feature flag lightning.autoFailover is enabled for the organization) Whether to use the enhanced messenger.
defaultOpen 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.
defaultClosed 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.
alwaysOpen No false Whether to force the messenger to stay open at all times.
googleApiKey No null The Google API key to use for when a Google map is displayed to the user.
customerReference No null A custom string reference for the conversation. It can be searched in Portal’s conversation history to find conversations that used it.
previewMode No false Whether to display pre-session welcome messages to the user before they interact with the messenger as floating message bubbles.
sbDiscoveryUrl No null 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.
messengerPosition No 'right' Defines on which side of a page the messenger should appear. Can be 'left' or 'right'.
forceMessengerExpanded No false When enabled, the messenger expands to full screen when open.
placeholderText No 'Write message' The prompt text to display to the user in the text area.
autoStart No false Whether to begin a conversation immediately, even before the roundel is clicked. When enabled, it skips showing the pre-session view from setting defaultOpen to true.
messengerTextAreaEventHandlers No undefined An object e.g. { onFocus: () => console.log('focused!'), onBlur: () => console.log('unfocused!') } of event handlers for the text area.
customStyle 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.
textInputDisabled 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.

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: