Our messenger supports more interactions than just user messages. It is possible for our bots send and receive commands straight from the host page where our messenger is configured.


  • Ensure your bot is Installed across the pages of the site where you require our messenger to appear, and configured appropriately.
  • Also make sure that the domain where you have your bot displayed is whitelisted in your endpoint

Host Notifications

The host webpage of our ServisBOT Messenger can receive notifications from our server (internally known as HostNotification) HostNotifications can be sent by as a Botnet Action or Node and are emitted to the host webpage by our messenger. To listen out for these notifications you can do the following.

const ServisBotApi = ServisBot.init({ ... }); //Initial configuration of our messenger
ServisBotApi.on('notification', function(message) {
    //  At the moment the message is just a simple string notification

Messenger Notifications

Messenger sends a limited set of events to the host page which can be used to determine user interaction during a conversation session. Current supported events are listed below.


Your host page can be configured as follows to respond to Messenger Notifications

const ServisbotApi = ServisBot.init({ ...your config params });
// Setup event listener to handle Messenger events
ServisbotApi.on('Messenger', (event) => {
    *   Each Messenger event has a type and a value
    *   the type is related to the specific interaction type
    *   of the event
    console.log(`Type: ${event.type}, Value: ${event.value}`);

ROUNDEL events

Event fired when the user opens the Messenger Roundel

  "type": "ROUNDEL",
  "value": "Opened"

Event fired when the user closes the Messenger Roudel

  "type": "ROUNDEL",
  "value": "Closed"


Event fired when the user interacts with the conversation for the first time during their session.

  "type": "CONVERSATION",
  "value": "First User Interaction"

Event fired when Messenger has loaded a conversation, and is ready to receive messages

  "type": "CONVERSATION",
  "value": "Ready"
  "identity": "COGNITO_IDENTITY"      //  Identifies the user within our system
  "converationId", "CONVERSATION_ID"  //  Identifies the conversation within our system

Private Host Notifications

Private Host Notifications are notifications that do not get emitted to the Messenger host webpage. Private Host Notifications are captured by Messenger and handled internally.

The supported Private Host Notifications are:

  1. SB:::UserInputDisabled - Will disable user input via the Text Input field at the bottom of the Messenger application.
  2. SB:::UserInputEnabled - Will enable user input via the Text Input field at the bottom of the Messenger application.
  3. SB:::MessengerOpen - Will open Messenger if Messenger is closed
  4. SB:::MessengerClose - Will close Messenger if Messenger is open
  5. SB:::MessengerPopup:::YOUR_DURATION - Will open messenger for the specified amount of seconds and then close. If the user interacts with Messenger before closing, Messenger will remain open. YOUR_DURATION is specified in seconds. eg. 3 - Messenger will open and finally close after 3 seconds.
  6. SB:::MessengerNavigate:::YOUR_URL - Will cause Messengers host page to navigate to the specified URL. You can supply an absolute url eg. or a relative url eg. /example. Note: If you wish to navigate to a new page with the same bot and immediately close the messenger on the new page, SB:::MessengerClose should be sent right before the SB:::MessengerNavigate. This prevents a race condition between the close host notification and the default messenger loading behavior.
  7. SB:::Typing:::YOUR_DURATION - Triggers the typing indicator. Optionally will timeout if amount of seconds are specified.
  8. SB:::MessengerStyle:::YOUR_ATTRIBUTE:::YOUR_VALUE - You can use this to update specific messenger style attributes during Bots conversation flow. Check the table below for customizable options
  9. SB:::UserInputNumericEnabled - Enables numeric input, showing numeric keyboards on mobile devices. Only digits are allowed to be entered when enabled. When the user sends a message, numeric input is automatically disabled.
  10. SB:::UserInputNumericDisabled - Disables numeric input if it’s enabled. This notification is sent automatically when any message is sent by the user.

Messenger Style Attributes

The SB:::MessengerStyle notification takes the following form SB:::MessengerStyle:::MESSENGER_STYLE_ATTRIBUTE:::MESSENGER_STYLE_VALUE. Where MESSENGER_STYLE_ATTRIBUTE is the style you would like to update eg. ROUNDEL_BACKGROUND_COLOR (the background color of messengers roundel) and MESSENGER_STYLE_VALUE is the value you would like to provide eg. #FF0000.

This would be configured as follows - SB:::MessengerStyle:::ROUNDEL_BACKGROUND_COLOR:::#FF0000

Supported customizable attributes include

Attribute Description Supported Value
MESSENGER_NAME Updates the current title of Messenger CSS Hex Value
MESSENGER_SUBITITLE Updates the current subtitle of Messenger CSS Hex Value
MESSENGER_LOGO Updates the current avatar of messages within Messenger URL Value
MESSENGER_BACKGROUND_IMAGE Updates the current background image of Messenger URL Value
MESSENGER_ROUNDEL_ICON Updates the current icon used by Messengers' Roundel URL Value
HEADER_BACKGROUND_COLOR Updates the current header background color of Messenger CSS Hex Value
HEADER_TEXT_COLOR Updates the current header text color within Messenger CSS Hex Value
FOOTER_BACKGROUND_COLOR Updates the current footer background color of Messenger CSS Hex Value
FOOTER_TEXT_COLOR Updates the current footer text color of Messenger CSS Hex Value
ROUNDEL_BACKGROUND_COLOR Updates the current Roundel background color CSS Hex Value
ROUNDEL_ICON_COLOR Updates the current Roundel Icon color CSS Hex Value
MESSENGER_BACKGROUND_COLOR Updates the current background color or Messenger CSS Hex Value
FOOTER_DISABLED_BACKGROUND_COLOR Updates the current background color used by Messenger when the textinput is disabled CSS Hex Value
FOOTER_DISABLED_TEXT_COLOR Updates the current text color used by Messenger when the textinput is disabled CSS Hex Value
BOT_MESSAGE_BACKGROUND_COLOR Updates the current bot message background color CSS Hex Value
BOT_MESSAGE_TEXT_COLOR Updates the current bot message text color CSS Hex Value
BOT_MESSAGE_BACKGROUND_SECONDARY_COLOR Updates the current bot message secondary background color CSS Hex Value
BOT_MESSAGE_TEXT_SECONDARY_COLOR Updates the current bot message secondary text color CSS Hex Value
BOT_MESSAGE_TERTIARY_COLOR Updates the current bot message tertiary color CSS Hex Value
SELECTABLE_INDICATOR_COLOR Updates the current selectable indicator color CSS Hex Value
USER_MESSAGE_BACKGROUND_COLOR Updates the current user message background color CSS Hex Value
USER_MESSAGE_TEXT_COLOR Updates the current user message text color CSS Hex Value
READ_ONLY_LINK_COLOR Updates the current read only link color CSS Hex Value
LIST_HEADER_BACKGROUND_COLOR Updates the current list header background color CSS Hex Value
WATERMARK_COLOR Updates the current watermark color CSS Hex Value

These can be configured as part of your flow using the hostNotification node and entering either value into the Notification Message field.

Page Events

Sending a Notification from Host Page to Bot can be done using page events. You use the following command to send the page event

const context =  {
        "some": {
            "data": {

***data*** provided in the body of the event data will be available at `payload.user.context`.

A string is also supported for sending the alias only without the body


For setting up the worker look here