ServisBOT Documentation > Product Features > Engagement Adapters > ServisBOT Messenger

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,
  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 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.
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 pre-session ‘Welcome! How can we help?’ view as seen in the internationalization settings below. Note: This shows only if `autoFailover` is true.
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.
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.

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)

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

Open developer tools (F12 or right click on the page -> ‘inspect element’)
At the top, click the ‘Network’ tab
There should be a dropdown for network throttling. Set this to ‘offline’.
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)

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.

Message Redaction

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

Messenger Redaction