Support livechat in a website

Note:

Support Integration

The support integration is the component that allows customers to communicate with support operators. Before embedding a support livechat, make sure that you receive your livechat-id and tenant-id from our support.

The support integration in a regular website happens by including a script from our server.

Bootstrapping the livechat

The livechat can be initialized via JavaScript. This is the preferred way if you're planning to use Serviceware Messaging as a support chat on your website.

To add a livechat to a regular HTML page, you have to first load the embeddable JavaScript file.

Loading the embed script

<script async defer src="https://<tenantId>-production-messaging-webchat.patty-awseuc1.swops.cloud/embed.js"></script>

As the snippet uses async defer to prevent blocking your own JavaScript, you have to wait for the window to be loaded before initializing the livechat.

To do this, copy the following snippet, which starts the chat in the most straightforward way.

livechat and configurationURL are required properties. You can find the values by opening your livechat in the livechat management.

Note: In the livechat management page, there's a "Copy snippet" action which allows you to copy the finished script with all the required configuration parameters.

Example on how to setup the chat

<script type="text/javascript">
  window.addEventListener('load', function () {
    // Initialize a livechat instance (Note: this doesn't start/insert it into DOM).
    var chat = new smoopeChat.default(document.body, {
      livechat: '<livechat-id>',
      configurationURL: 'https://<tenantId>-production-messaging-webchat.patty-awseuc1.swops.cloud/.well-known/web'
    });

    // Insert livechat instance into DOM.
    chat.insert();
  });
</script>

Once the chat is inserted, Serviceware Messaging will automatically show a button to let the user request support if possible.

Note:

Chat visibility

Depending on your livechat configuration, the button will only appear in some cases, e.g. if a matching operator is available.

Options

The chat initialization has the following constructor signature:

Chat constructor

class Livechat {
  constructor(parent: HTMLElement, options: LiveChatOptions = {}) {}
}

LiveChatOptions

type Preconditions = Record<string, any>;
type TranslatedLanguage = 'en' | 'de' | 'it' | 'fr';

interface LiveChatOptions {
  livechat: string;
  preconditions?: Preconditions;
  language?: TranslatedLanguage;
  captureLinks?: boolean;
}

This means to construct the chat you have to pass in:

parent: HTMLElement - the element that the chat appends itself to
options: LiveChatOptions - (optional) the options that configure the chat, as mentioned above

The instance can be configured by setting the options object. You can adjust the following fields:

livechat: string - the livechat id
configurationURL: string - the livechat configuration URL
captureLinks: boolean - (optional) a click on any link in the chat history will prevent transition and emit a CapturedLink event
preconditions: object - (optional) an object that is used to improve operator routing. If you don't use any special routing logic, you shouldn't have to set it
language: string - (optional) a hint that influences the language, the system is using, for the support user.

Methods

on(topic: string, cb: Callback): void - registers a function that is called for a specific event
once(topic: string, cb: Callback): void - registers a function that is called for a specific event only once
insert(): void - inserts the chat into the DOM
destroy(cb: CallBack): void - cleanly removes the chat from the DOM. The callback is called once everything is removed.
requestSupport(): void - triggers the chat to behave as if a user requested support manually

Examples

Listening for events

The returned chat instance acts as an event emitter and emits various informations to your website. The following events are observable from your website:

captureLinks, if the captureLinks option is enabled with {url: string} as event payload

Example on how to capture link clicks

var chat = new smoopeChat.default(document.querySelector('#chat'), {
  // ... other options
  captureLinks: true
});

chat.on("capturedLink", function(data) {
  alert(`user clicked a link: ${data.url}`);
});

// Insert livechat instance into DOM.
chat.insert();

Opening the chat automatically on desktop screens

If you want to automatically start a support conversation for visitors that use a desktop browsers (width > 768px), you can simply do that by implementing it in the following way:

Example on how to automatically start a chat on desktop browsers

var chat = new smoopeChat.default(document.querySelector('#chat'), {
  // ... other options
});

if (matchMedia('(min-width:768px)').matches) {
  chat.once('visible', function () {
    chat.requestSupport();
  });
}

// Insert livechat instance into DOM.
chat.insert();