Chatlio widget API

If you want your own web app to control and interact with your Chatlio widget you can use the Chatlio API features described below.


  1. For best results, wrap all api calls in chatlio.ready documented below.
  2. Make sure you are always using the latest embed code found here.


When your web page loads, the Chatlio widget initializes itself and contacts the Chatlio server to fetch meta data, such as your team’s online status, customized text for the widget UI and other configuration data. What this means in practice is the widget markup is not available immediately on page load, but inserted after Chatlio finishes loading.

The API is designed in such a way as to let you execute code without waiting for Chatlio to initialize, instead queueing up API calls and execute them as soon as possible.

Use the global object window._chatlio to make API calls.

When using the API to control when and how to display Chatlio, it can be useful to provide an extra attribute to the widget initialization code to force the widget to stay out of the way until your own code summons it: data-start-hidden . Add this to your embed code:

  n.setAttribute('data-start-hidden', true);

Custom events

The Chatlio widget will emit events to help you integrate it more tightly into your own website.


When the Chatlio widget has finished loading and initializing the data it needs it emits a custom event, chatlio.ready . Your code can listen for this and execute your own code at the right time.

The chatlio.ready event is emitted when the widget has a DOM node and have successfully registered with Chatlio (which in turn opens channels and sockets sets everything up for chatting). For instance, you can detach the widget DOM node and move it to wherever you please in your DOM tree. You can also use the API freely, calling e.g. . This event is guaranteed to emit once per page load.


  document.addEventListener('chatlio.ready', function (e) {
    console.log("[chatlio.ready] e: %o", e);
    var chatlioNode =;
    console.log("[chatlio.ready] widget DOM node: %s (children: %d)", chatlioNode, chatlioNode.childNodes.length);
    // Remove chatlio and stick it somewhere else:

    // It's safe to use the API of course;
  }, false);


When the visitor sends their first message to you, effectively initiating a new chat, the chatlio.firstMessageSent event is emitted.


  document.addEventListener("chatlio.firstMessageSent", function(event){
    console.log("[chatlio.firstMessageSent] event: %o", event); // Do something interesting


When the visitor sends a message, the chatlio.messageSent event is emitted. The data payload contains the message data.


  document.addEventListener("chatlio.messageSent", function(event){
    console.log("[chatlio.messageSent] event: %o", event); // Do something interesting


When the widget receives a message from Slack, the chatlio.messageReceived event is emitted. The data payload contains the message data, including the Slack channel ID of the conversation.


document.addEventListener("chatlio.messageReceived", function(event){
    console.log("[chatlio.messageReceived] event: %o", event); // Do something interesting


When the visitors submits the pre-chat (ask for name & email) form, the chatlio.preChatInfoSubmitted event is emitted. The data payload contains the email address and name.


document.addEventListener("chatlio.preChatInfoSubmitted", function(event){
  console.log("[chatlio.preChatInfoSubmitted] event: %o",; // Do something interesting


When the widget visibility is changed we emit this event. In addition to other meta data, we emit the “visibility” state as “open” or “closed”. We also emit on first load. Useful when creating your own button to control Chatlio. See “style of widget when closed” option in the dashboard for more info on how to use.


  document.addEventListener("chatlio.visibilityChange", function(event){
    console.log("[chatlio.visibilityChange] event: %o", event); // Do something interesting


When the widget is collapsed the chatlio.collapsed event is emitted.


  document.addEventListener("chatlio.collapsed", function(event){
    console.log("[chatlio.collapsed] The widget is now minified"); // Do something interesting


When the widget is expanded the chatlio.expanded event is emitted. Note: this even is not fired when using the API to show the widget in expanded mode with{expanded: true}).


  document.addEventListener("chatlio.expanded", function(event){
    console.log("[chatlio.expanded] The widget is now expanded, maybe we'll get a message soon?");


When the widget fires a triggered message the chatlio.trigger event is emitted.


  document.addEventListener("chatlio.trigger", function(event){
    console.log("[chatlio.trigger] The widget fired a trigger event: %o", event);


When the widget transitions to offline the chatlio.offline event is emitted.


  document.addEventListener("chatlio.offline", function(event){
    console.log("[chatlio.offline] The widget has went offline");


When the widget transitions to online the event is emitted.


  document.addEventListener("", function(event){
    console.log("[] The widget has went online");


When the visitor or the operator ends the chat, the following event is emitted. The event payload looks like the following:

{endedBy: "operator", conversationUUID: <conversation UUID>}


  document.addEventListener("chatlio.conversationEnded", function(event){
    console.log("[chatlio.conversationEnded] The widget fired a conversationEnded event: %o", event);


By default when the visitor or the operator ends the chat, the message history is cleared. You can prevent this using _chatlio.configure()


_chatlio.configure({clearMessagesOnEnd: false});

API methods


Use _chatlio.identify() to send information about the visitor to your site to Chatlio. This information will be displayed in Slack with the initial message they send, giving your team an easy way to contextualize the visitor.

The first param should be a unique string that identifies the visitor, like user ID or email.

The second param is a hash of your own custom data that will be printed in Slack when visitor starts a conversation. We also give special treatment to “name” and “email” params. See below.


  _chatlio.identify('user1234', {
    name: 'Elvis Presley',
    email: '',
    plan: 'king',
    favoriteColor: 'black'

Chatlio uses the data you pass in to name the Slack channels. We name the channel based on this following:

  • If we find “name” param, we use that for channel name, eg. #z-amy-smith-123
  • Else we find “email” param, we use that for channel name, eg. #z-asmith-gmail-com-123
  • Else we use userId for channel name, eg. #z-user1234
  • If identify() is not used, we name channel after geo-location, eg. #z-san-francisco-ca-usa-123


Returns a boolean, true when Chatlio is available and showing on screen, false when Chatlio is hidden or not yet initialized.


  if(_chatlio.isShown()){ alert("Thanks for chatting!"); }


Open the widget expanded. Alias for{expanded: true});

Here’s how you could attach a click handler to a button to open the Chatlio widget:

  <button onclick=";">Open Chat</button>


Show the widget on screen. If Chatlio is not yet initialized, the widget will be shown after a short delay.

Here’s how you could attach a click handler to a button to make the Chatlio widget visible:

  <button onclick=";">Unhide Chat</button>

If you want the widget to show fully expanded or collapsed, regardless if the user clicked on the title bar of the widget, pass in an options object to set the expanded property to your preference.

Example:{expanded: true});

Example:{expanded: false});

Example Use Case:  Open widget with button or link

See the Pen Example use: open Chatlio widget with button by Chatlio (@chatlio) on CodePen.


Hide the widget.

Here’s how you could attach a click handler to a button to hide the Chatlio widget:

  <button onclick="_chatlio.hide();">Hide Chat</button>


showOrHide toggles the widget visibility from shown or hidden. Useful when creating your own button to control Chatlio. See “style of widget when closed” option in the dashboard for more info on how to use.

Here’s how you could attach a click handler to a button to showOrHide the Chatlio widget:

  <button onclick="_chatlio.showOrHide();">Toggle Chat Visibility</button>


Returns a boolean, true when Chatlio is connected to the backend (even if it is not currently showing on screen) and there is somebody available on your Slack team to reply to chats.


    alert("It's on! Chat away!");


Dynamically set configuration options for the widget. Useful for multi-language support or to dynamically set label text from javascript. Any attributes you omit will be set from data you configure in the Chatlio web UI.

NOTE: when you run _chatlio.reset() the data set through _chatlio.configure() is also reset. If this is undesirable to you, run the configure call again.


     "noAnswerWithEmail": "Oops! Sorry no one has responded yet. We have your email on file if you need to leave or you can continue to wait.",
     "noAnswerWithoutEmail": "Oops! Sorry no one has responded yet. We have your email on file if you need to leave or you can continue to wait.",
     "onlineTitle":"How can we help you?",
     "offlineTitle":"Contact Us",
     "onlineMessagePlaceholder":"Type message here...",
     "offlineGreeting":"Sorry we are away, but we would love to hear from you and chat soon!",
     "offlineMessagePlaceholder":"Your message here",
     "offlineNamePlaceholder":"Name (optional but helpful)",
     "offlineThankYouMessage":"Thanks for your message. We will be in touch soon!",
     "requireInfoGreeting":"Enter your name and email to start chatting!",
     "requestScreenshotText":"Operator would like to take a screenshot of your browser. Confirm below.",
     "requestScreenshotAllowLabel":"Take screenshot",
     "conversationEndLabel":"Your chat session has ended. Thanks for chatting!",
     "conversationRatingLabel":"How would you rate this chat?",
     "conversationRatingThankYou":"Thanks for rating your chat session!",
     "conversationRatingPlaceholder":"How can we improve?",
     "conversationEndTranscriptPlaceholder":"Email to send transcript of chat",
     "conversationEndConfirmationQuestion":"Are you sure you want to end this chat?",
     "conversationTranscriptSentThankYou":"Thanks! You will receive your transcript shortly.",
     "conversationEndMenuLinkLabel":"End Chat",
     "autoResponseMessage":"Question? Just type it below and we are online and ready to answer."

Note: you can check most up to date list by looking at[your widget id]

You can configure the time-related strings Chatlio uses in the messages list to your locale like this:

    timeLocale: {
      "just now": "juste maintenant",
      "y ago":    " ans",
      "mo ago":   " mois",
      "d ago":    " jours",
      "h ago":    " heures",
      "m ago":    " minutes"


Returns ISO country code of current visitor.




Reset the Chatlio widget and issue a new visitor UUID.

Sometimes you want to reset the Chatlio widget and prepare it for a new chat.




Permanently remove all chat history from the current session while keeping the visitor session active.

If you need to clear a visitors message history without resetting the session entirely you can use _chatlio.clearHistory(). The operator in Slack will still see the full message history.




If you have more than one Chatlio widget, each connected to its own Slack channel and need to switch between them on the same page, use _chatlio.switchWidget() and pass the UUID for the widget you want to switch to. Perhaps you’re building a custom UI to let your visitors select between different support teams and want to let them connect to the right people at the click of a button?


  var button = document.querySelectorAll("#some-selector")[0];
  button.addEventListener("click", () => {


Send a message to Slack from the browser.

If you need to send a message from the browser to Slack you can use _chatlio.send(). The message sent is indistinguishable from a normal message from the visitor and will show up in their widget chat history. If no previous messages were sent, _chatlio.send() will start a new conversation in Slack.


  _chatlio.send("This message is sent programmatically");

NOTE: _chatlio.send() will not work if the Chatlio widget has not been rendered, e.g. if data-start-hidden is set to true and before you called yet. If you want to send a message in this situation, use"hello world").



Method to return visitor messages.

Example, only load widget on a specific page:

Perhaps you want to load the widget on a specific page only if a visitor has already started a conversation. In some cases, you may not be able to load the embed code individually or are worried that when a user navigates to another page (where the widget is not loaded), the widget will disappear.

First, add the following line to your embed code, this forces the widget to stay hidden until your own code summons it.

n.setAttribute('data-start-hidden', true);

Second, utilize the _chatlio.messages() method to check if the visitor has an active chat and then only load the widget if they have an active conversation.

Example, only load the widget on /pricing page if messages exist:

<script type="text/javascript">
document.addEventListener('chatlio.ready', function(e) {
    var showPage = "/pricing";
    if (_chatlio.messages().length > 0 || document.location.href.indexOf(showPage) > -1) {


Tell Chatlio about a dynamic page change so chatlio will know current page and evaluate triggers for auto messaging.

NOTE: Only useful for customers using single page apps (React, Angular, Meteor, etc) that do not emit onpopstate event on route change.

Chatlio does try to detect page changes by monitoring the onpopstate event. But that doesn’t work for all javascript routing libraries. In that case, we recommend you call from your app when a route changes.

If you aren’t sure whether Chatlio is detecting your SPA page changes, check with _chatlio.debug().

Tell Chatlio about a page change:;


Programattically fire “triggered” messages like you can setup here.

Assuming you have your own logic for a shouldShowTriggerHere() function, see following example.

if (shouldShowTriggerHere()) {
  _chatlio.trigger({message: "Help is available!", after: 0});

Note: You can only fire one trigger per hour, and triggers with a uid that has been seen before by visitor will not be shown.

_chatlio.trigger() takes the following arguments.

  message: "automessage text here",
  after: 30, // seconds,
  displayStyle: "peek", // OPTIONS: "peek" or "full"
  uid: "optional-uid-string-here"


We do our best to show the widget in the best manner for the device resolution, but sometimes you may want to force full screen mode on chat widget when expanded, example Phablets.

This is an example of how you can force expanded mode to be full screen and then disable if you want. This does not persist so you must call it on each widget render.

document.addEventListener('chatlio.ready', function (e) {
  var deviceNeedsFullScreen = true; // put your logic here.

  if (deviceNeessFullScreen) {
    // force full screen when expanded (required after each load, not persistent)

     // probably don't need this option, but in case you do.
      console.log("disable full screen after 5secs");
      // disable full screen when expanded

}, false);


If desired, you can prevent Chatlio from using cookies to store visitor session data by adding the one line below to your embed code.

To disable cookies site wide, update your embed code with data-chatlio-cookies attribute.

<script type="text/javascript">
    // embed code cut for brevity
    n.setAttribute('data-widget-id','<your widget ID here>');
    n.setAttribute('data-disable-cookies', true); // <–– ADD THIS

note; Enabling this attribute will disable the ability for visitor sessions to perist accross sub-domains.


In order to help debug triggers and future Chatlio features, we have added a way to output debugging logs in the developer console.

To turn it on site wide, update your embed code with data-chatlio-debug attribute.

<script type="text/javascript">
    // embed code cut for brevity
    n.setAttribute('data-widget-id','<your widget ID here>');
    n.setAttribute('data-chatlio-debug', true); // <–– ADD THIS

To turn it on temporarily.

  _chatlio.configure({debug: true});
Your browser is out-of-date!

This website is built using latest technogies. Unfortunately your browser doesn't support those. Please update your browser to view this website correctly. Thank you.Update my browser now