Embedding the widget

In the simplest case, you just pick up the JavaScript snippet from the page of your WEB channel and add it to your website. Read on if you’d like to know what the snippet actually does or customize your widget further.

What the JS snippet does

The JS snippet contains the definition of a configuration object and a user object, and an initialization script.

The configuration object (mercuryConfig) contains at least the apiKey that is needed to link the widget to your channel. It may contain some more settings that affect the widget’s behavior and are explained further below. The user object (mercuryUser) contains a startIntent if you choose one from the dropdown. You may add more configuration to the user object if needed – see setting up the user.

The initialization script does the following: First, it checks if the widget JavaScript and CSS are already linked and links them if not. As soon as the widget JS is loaded, the script checks if the widgets div element is already present and adds it if not. Third, it initializes the widget.

Actually, you don’t need the initialization script but can do everything yourself (which might be reasonable in more complex scenarios). What you have to do in this case will be explained in the following.

Linking Javascript and CSS files

As a first step for running the widget on your website, you have to link the JavaScript and CSS files.

Add the following code to your HTML head:

<link href="https://widget.mercury.ai/v3/widget.css" rel="stylesheet">
<script src="https://widget.mercury.ai/v3/widget.js"></script>

If you want to customize the widget’s styling with your own CSS, you can use this CSS file as a template and read on under Styling the widget below.

Setting up the configuration

As mentioned above, the widget needs a configuration object that contains at least your channel’s key. You might define it like this:

var mercuryConfig = {
  apiKey: <your channel’s key>
};

The object may additionally contain some settings that determine how the widget behaves:

• displayMode (string): How to display the widget. It has the two possible values "overlay" (default) and "block" for the chat window to be displayed floating above the page or as an in-page element, respectively. For the "block" option, you must insert the element <div id="mercury-widget"></div> at the place in your HTML where the widget should be displayed.
• fullscreen (boolean): Only applicable in overlay mode. true opens the widget in fullscreen mode, false (default) opens the small version.
• active (boolean or integer): Only applicable in overlay mode. true means that the widget is open when the page is loaded, false (default) means that the widget is closed. You also have the option to open it with a delay by setting a value in milleseconds.
• pollingInterval (false or integer): This enables the widget to poll for new messages. Use this if and only if your bot has a handover mode. Provide the polling interval in seconds, i.e., the smaller the number, the more frequently polling is executed. So, if needed, we recommend to set pollingInterval to a number between 5 and 10.

Setting up the user

When users are communicating with an AI assistant, it is necessary for the system to unambiguously recognize the user it is communicating with. This is important because users want to have a conversation where they see their full length interaction, which is only possible when the bot knows if a message comes from user C or user D. That is why each user needs a unique ID.

If you don’t provide a user object with an ID, the widget creates a random ID, which is then stored in a cookie (named mercuryUserId) so the user is recognized when the page is loaded anew. The same happens if you provide a user object which doesn’t have an ID. When you provide your own ID (e.g., for logged-in users), take care it is unique for each user!

Apart from the userId, you may set the properties firstName and lastName if you have access to the respective information. Also the user’s language may be set (use an ISO 639-1 code like “en” or “de”).

If you want to set a first intent that is being triggered when the widget opens up, you can also do this right here. Say you want the intent to be from the game “Intro” and the intent’s label is “Start”. To set this as start intent, you add the property startIntent with its value like this:

startIntent: 'Intro/Start()'

Pro Tip: You can also work with context parameters in mercuryUser. Add a property called context which can then be filled with context parameters. You can do this with the global context, and it will look like this:

context: {
  global.Book: 'LOTR'
  global.Page: '1',
}

For your bot to retrieve and handle the context you need to generate a global context variable with the exact same label. Now you can work with the context variable through the web app and the widget.

To sum up, a user object could look like this:

var mercuryUser = {
  userId: <your custom user ID>,
  firstName: 'John',
  lastName: 'Doe',
  startIntent: 'Intro/Start()',
  context: {
    global.book: 'LOTR',
    global.page: 1
  }
};

Adding the HTML element

The widget needs an element in your HTML to which it can be mounted. This element is just a div element with the ID mercury-widget:

<div id="mercury-widget"></div>

If you use the widget in overlay mode, it doesn’t matter where in your HTML document the element is located. However, if you use the widget in block mode, the element needs to be in the location where you want it to be displayed.

Initializing the widget

When JS and CSS files are linked, config and user objects are set up and the HTML element is in place, the last step is to initialize the widget. To this end, call the initialization function Mercury.initChatWidget with the HTML element, the config object and (optionally) the user object:

Mercury.initChatWidget(
  document.getElementById('mercury-widget'),
  mercuryConfig,
  mercuryUser
);

Styling the widget

If you want to customize the widget’s styling with your own CSS, you can use this the CSS file theme.css as a template. Make sure to include theme.css after widget.css.

This file contains some key styles alongside with comments. Note that all rules should be nested under the #mercury-widget selector in order not to compromise your page’s styling. (You may, however, face the situation that your page’s CSS compromises the widget’s styling by (too) general rules. In this case there is no solution but adjusting your page’s CSS.)

Events

In order to further integrate the chat widget and your page, the widget offers an interface to send events to the bot in a systematic fashion and to receive widget-specific events.

This feature can be used, e.g., for keeping a form on your page in sync with a form filling game in your bot, so the user can switch seamlessly between form and chat.

Events emitted by the widget

The events emitted by the chat widget are all emitted at the #mercury-widget element, they bubble and are cancellable. The following events are emitted:

• text-sent: when a text message is sent off to the bot
• intent-sent: when an intent is sent off to the bot (e.g. start intent or button click)
• location-sent: when a location is sent off to the bot (location button)
• messages-received: when bot messages are received
• message-added: when a new bot message or handover message is displayed
• bot-event-received: when a bot event is received. The detail property of the event contains further information about the bot event.

Sending events to the bot

You can send user intents as events to your bot. To this end, the widget element offers the sendEvent method.

sendEvent takes as argument an object with the two properties silent (boolean) and payload (object). silent (optional) tells the bot not to send a message as reaction to the sent intent (default is true). payload contains the information to send and can contain context updates or intents (with or without slots) or both:

{
  silent: true,
  payload: {
    contextUpdates: [
      <context update>
    ],
    game: <string>,
    intent: <string>,
    slots: [ <slot> ]
  }
}

For the definition of slots and context updates, please refer to the common datatypes section.

Chat widget cookies

When using the Mercury.ai chat widget, two cookies are set by default to ensure the widget's functioning. These cookies have a preconfigured expiration after 540 days.

The first cookie is the mercuryUserId which is set to uniquely identify a user who is communicating with a Mercury.ai assistant. This enables the system to unambiguously identify the dialogue and to display the interaction between assistant and user correctly.

The mercuryUserId cookie is set by the widget in cases in which the widget is missing a value for the userId - it is designed as a fallback to guarantee the functionality of your assistant. Once the userId is set up correctly-as described in setting up the user-, no cookie is created by the chat widget itself.

Besides the mercuryUserId there is also a cookie called mercuryWidgetState. This cookie is used to remember the state of the widget (open or closed) and to guide users through your website in the way they want - open or closed widgets remain in the desired state until a user actively makes a change.