Website Messenger API Tutorial

In case you’re still using the messenger API of our Live Chat product: it will continue to work and you can still access its documentation here. If you’re setting up the messenger API for the first time, we recommend doing so in our Unified Messaging product, as we’ll only update and extend the API here.

With our messenger API you can control the Website Messenger’s behavior and integration beyond the options we provide in our Messenger settings. To go directly to the API’s full documentation on GitHub, click here.

The messenger API allows you to define the start and flow of your chat communication based on your website’s behavior, events and functions. A few potential use cases to give you a better idea:

  • Loading the Website Messenger only after a cookie consent
  • Triggering the chat in certain situations, e.g. a shopping cart exceeding a certain value
  • Loading and removing the Website Messenger on larger single page applications

When you use the JavaScript Widget code to load your Website Messenger, it’s loaded globally, as soon as the script tag is executed. The Messenger API gives you more control over the loading process by allowing you to “mount” and “unmount” Messengers (adding or removing them on the document).

The setup of the Messenger API is geared towards developers. This tutorial is meant to also give less technically versed users an overview of the Messenger API and its possibilities. The canonical reference for the Messenger API is this GitHub repository, which contains its code.

The examples provided in this document use plain JavaScript. You might want to consider using utility libraries that help you handle promises more easily.

Using the API

In order to use commands with the API, you will need to create a messenger object, which can be done using the `createMessenger` function from the `@userlike/messenger` npm package. Here’s a simple way to do it, but we recommend to add error handling to your function in case something goes wrong or in case the API version you’re using has reached its end-of-life. First, make sure to import the required component from the npm package at the top of your file: `import { createMessenger } from '@userlike/messenger';`

You can now use `createMessenger` in your code:

Now assign this function, which returns a promise, to a variable. You can then use that to mount the messenger on the DOM, for example:

The above is a good example of how you could tie creating and mounting the messenger to a user's cookie consent choices by only calling `createApi()` after the user has selected the relevant option.

Only one messenger can be mounted to the DOM at a time, so please make sure you consider this in your logic, especially if you are aiming to switch between different widgets. If you try to mount a second widget even though there is already another one mounted, this will result in an error.

Using your own element to trigger the chat

In certain situations, you might want to use a custom element on your page to trigger opening the messenger instead of the widget's button. In that case, you will likely want to use the `setVisibility` function of the messenger API. Using `setVisibility`, you can define the visibility of `main` (the main window of the chat widget), `button` (the button itself) and `notifications` (notification bubbles such as the welcome bubble or the proactive bubble).

In combination with the maximize function, you could define your own element and define that the onClick event should trigger maximizing the messenger. Assuming you're using an HTML element with the ID `myBtn`, you could do something like this:

You could expand on this starting point by changing the above `startChat()` function to toggle the messenger's visibility between maximized and minimized or only display your custom button if the messenger is minimized. The messenger's current state can be retrieved using the API's `getState()` function, which we'll expand upon further in this tutorial. For more information on state tracking, please also refer to the code example in the Github repository.

Displaying the messenger based on certain conditions

The concept of changing the visibility or mounting the messenger as seen above can be applied to different scenarios where you'd like your own logic to determine when the button should be shown to your visitor.

For example, let's say you'd only like to display the button after the visitor has reached a certain point on your page, you'd just call the `setVisibility()` function with the relevant arguments:

The same idea can be transferred to different scenarios, such as updating the visibility of the button once a customer has reached a certain cart value. Used judiciously, you can create different scenarios to boost chat engagement by offering the chat at just the right time..

Sending data to the messenger

The API provides two functions that allow you to send data to the messenger.

`setContactInfo` allows you to set the contact's name and email address. This is useful if you are offering the chat for users logged into your web application and you want to pass this information directly to Userlike.

The data should be passed to the function as a Javascript object containing the keys `name` and `email` with the corresponding values as strings..

If you are using the widget in registration mode and you pass the contact's name and email to the messenger, the registration step when starting a conversation will be skipped..

The same logic can be used with the custom data function. You custom data will show up in the Message Center. It can be updated by calling the `setCustomData` function again with an updated set of data. The data you pass to the messenger should be a Javascript object containing key-value pairs with the information you want to include..

The below example mounts the messenger, sets the contact's name and passes some custom data to the conversation.

Getting the widget's current state

To retrieve the Messenger’s current state, use the API’s `getState()` function. It can return three different values:

  • `hidden`: when the Messenger hasn’t been mounted on the DOM, or when it has been mounted but it’s set to be hidden through the Messenger’s configuration. This would be the case if you’ve set the Messenger to be hidden when no operator is available in the Message Center. You can use this information to determine whether to show or hide certain elements on the page based on your operators’ availability.
  • `minimized`: the Messenger is mounted but minimized (the main Messenger window is not displayed).
  • `maximized`: the Messenger is mounted and maximized (the main Messenger window is displayed, just like after clicking on the Messenger button).

Instead of querying the state manually, you can also do this by subscribing to the state. For more information refer to the the GitHub repository.