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).
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.
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.
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.
Displaying the messenger based on certain conditions
The concept of changing the visibility or mounting the messenger 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, you can 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.Additional keys can be
phone_number, mobile_number, company and external_customer_idIf 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. Your 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.
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.
Contact Authentication and Verification
Contact authentication and verification enable your Contacts to prove their identity. Once authenticated, they can access their ongoing and previous conversations. Contact authentication and verification are important for ensuring the security and integrity of your Contacts' conversations so that you are protected against impersonation attacks, prevent duplicate Contacts, and provide a seamless user experience.
Contact Authentication
A first-time visitor implicitly creates a new Contact for themselves. They are authenticated every time they visit the website, allowing them to access their ongoing and previous conversations. The credentials for a Contact are stored in the browser storage. However, if a Contact switches devices or clears the browser storage, they will implicitly create a new Contact for themselves again, losing access to their conversations from the other device.
Contact Verification - recommended
Contacts can verify their identity via their email address or when using Messenger API Contact Authentication via a unique identifier that you control and associate with a Contact. Verified Contacts reduce the possibility of duplicate Contacts and give Operators certainty that Contacts are who they claim to be. Operators can see the verification state and the kind of verification for a Contact via the verified Badge on Contact Avatars in the Message Center.
Email Verification
When a Contact has previously entered their email address, they can regain access to those conversations by either clicking the conversation link in the email that notifies them about unread operator messages or proactively request a "magic link" with a one-time authentication token to be sent to their email address.
Messenger API Contact Authentication
In addition to email verification, we offer a way to authenticate and verify a Contact using the Messenger API Contact authentication. This allows you to associate a unique identifier with a Contact, usually after they have logged into your system.