Chat widget

Embedding the widget

In the simplest case, you just pick up the JavaScript snippet from the page of your WEB channel (Configuration > Channels > edit settings). There you find it in the section Embedding the chat widget.

With this embedding snippet you are good to go to running a Mercury assistant on your web page. However, for a deeper understanding and more complex implementation cases, you should go on reading.

What the JS snippet does

The JS snippet contains the definition of an application with a certain id and a data-key and a stylesheet that applies your design decisions.

The web widget application is fetched from a source (src="https://cdn.mercury.ai/widget/v4/widget.js") that contains the current version of the widget. It is followed by an id and the data-key which unambigously identifies the channel. Without it, there is no connection between your bot and the frontend display of the widget.

The second part of the embedding script is the design part. It consists of the definition of the link as a css stylesheet which is connected to the styling file. The file can be changed through making different settings directly on the web channel. This means that the designs done on the web channel configuration page are automatically applied to your widget.

In the channel configuration page at the bottom you also find settings for creating teaser messages. For each teaser message a certain condition can be selected through a drop down list. This condition decides when a teaser message should appear in the bot.

Setting up the user

For a function widget setup on your website it is not necessary to define the user in any way - everything is already set up for you. However, if you want to work with your own user object, you can do that as well. This is especially important in cases where you want to have a deeper integration of the bot on your website.

The mercuryUser script should be added right after the widget initialization script. There you can define various attributes about users like the name, the company or any other user context variable - for a full list, go to this page.

If you don’t provide a user object with an ID (the userId), the widget creates a random ID, which is then stored in a cookie (named mercuryUserId). The user ID is necessary for making a conversation between user and bot possible. If you use an ID that persists, the user is recognized again and the chat history is also fetched. The same happens if you provide a user object which doesn’t have an ID - the mercuryUserId is created automatically. 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”).

You can also work with context parameters in mercuryUser. For this you have to add a property called context which will then set context parameters. You can do this e.g. for global context variables:

context: {
  global.landingPage: 'Campaign23',
  global.referral: 'Ad'
}

For your bot to retrieve and handle the context you need to generate a global context variable with the exact same label directly in your bot project on the Mercury Webapp. Now you can make a connection between the context set by the website through the widget and the context parameters you defined for your bot.

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

var mercuryUser = {
  userId: <your custom user ID>,
  firstName: 'John',
  lastName: 'Doe',
  context: {
    global.landingPage: 'LOTR',
    global.referral: 'Ad'
  }
};

Styling the widget

The styling of the widget can in the most parts be done via the channel configuration page of your web channel. There you can, among many other options, define the color of the bubbles, the settings of quick reply buttons as well as the header logo image.

However, there is also the option of customizing the widget in more detail. For that you can use your own CSS which you can design. Make sure to include your custom css after the stylesheet part of the snippet.

The theme.css 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. 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.