If you want your own web app to control and interact with your Chatlio widget you can use the Chatlio API features described below.
chatlio.ready documented below.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 data-start-hidden to your embed code as seen below:
<chatlio-widget data-start-hidden widgetid="<your widget ID here>"></chatlio-widget>
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. _chatlio.show() . This event is guaranteed to emit once per page load.
Example:
document.addEventListener('chatlio.ready', function (e) {
console.log("[chatlio.ready] e: %o", e);
var chatlioNode = e.target;
console.log("[chatlio.ready] widget DOM node: %s (children: %d)", chatlioNode, chatlioNode.childNodes.length);
// Remove chatlio and stick it somewhere else:
document.getElementById("otherContainer")
.appendChild(chatlioNode.parentNode.removeChild(chatlioNode));
// It's safe to use the API of course
_chatlio.show();
}, false);
When the visitor sends their first message to you, effectively initiating a new chat, the chatlio.firstMessageSent event is emitted.
Example:
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.
Example:
document.addEventListener("chatlio.messageSent", function(event){
console.log("[chatlio.messageSent] event: %o", event); // Do something interesting
});
When the visitor submits an offline message, the chatlio.offlineMessageSent event is emitted. The data payload contains the offline message data, including the Slack channel ID of the conversation.
Example:
document.addEventListener("chatlio.offlineMessageSent", function(event){
console.log("[chatlio.offlineMessageSent] 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.
Example:
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.
Example:
document.addEventListener("chatlio.preChatInfoSubmitted", function(event){
console.log("[chatlio.preChatInfoSubmitted] event: %o", event.data); // Do something interesting
});
When the visitor selects a question group answer, the chatlio.questionGroupAnswerSelected event is emitted. The data payload contains the question text, customResponseText (if applicable), and the action that follows the selection. Learn more about question groups on our question groups doc page.
Example:
document.addEventListener("chatlio.questionGroupAnswerSelected", function(event){
console.log("[chatlio.questionGroupAnswerSelected] event: %o", event.data); // 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 open and close your widget.
Example:
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.
Example:
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 event is not fired when using the API to show the widget in expanded mode with _chatlio.show({expanded: true}).
Example:
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.
Example:
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.
Example:
document.addEventListener("chatlio.offline", function(event){
console.log("[chatlio.offline] The widget has went offline");
});
When the widget transitions to online the chatlio.online event is emitted.
Example:
document.addEventListener("chatlio.online", function(event){
console.log("[chatlio.online] 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>}
Example:
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()
Example:
_chatlio.configure({clearMessagesOnEnd: false});
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.
Example:
_chatlio.identify('user1234', {
name: 'Elvis Presley',
email: '[email protected]',
plan: 'king',
favoriteColor: 'black'
});
Chatlio uses the data you pass in to name the Slack channels. We name the channel based on this following:
Returns a boolean, true when Chatlio is available and showing on screen, false when Chatlio is hidden or not yet initialized.
Example:
if(_chatlio.isShown()){ alert("Thanks for chatting!"); }
Open the widget expanded. Alias for _chatlio.show({expanded: true});
Here’s how you could attach a click handler to a button to open the Chatlio widget:
<button onclick="_chatlio.open();">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="_chatlio.show();">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:
_chatlio.show({expanded: true});
Example:
_chatlio.show({expanded: false});
More complete example:
<button id="chatlio-show-btn">Show</button>
<script>
const chatlioShowBtnEl = document.getElementById('chatlio-show-btn');
chatlioShowBtnEl.addEventListener('click', () => {
_chatlio.show({ expanded: true });
});
</script>
<script src="https://js.chatlio.com/widget.js" async></script>
<chatlio-widget widgetid="<INSERT YOUR WIDGET ID HERE>"></chatlio-widget>
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 open and close your widget.
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.
Example:
if(_chatlio.isOnline()){
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 dashboard.
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.
Example:
_chatlio.configure({
"off":false,
"maxVisitorInactiveMins":3,
"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.",
"status":"online",
"hideWhenOffline":false,
"showAvatarPreChat":false,
"showTeamAvatarPreChat":false,
"newMsgNotifications":true,
"playSound":true,
"dialogflowOn":false,
"watsonconvOn":false,
"activeAgentAvatar":"",
"forwardSlackUserName":false,
"widgetAlignment":"bottomRight",
"titleColor":"#3f51b5",
"titleFontColor":"#fff",
"onlineTitle":"How can we help you?",
"offlineTitle":"Contact Us",
"agentLabel":"Support",
"browserSideAuthorLabel":"",
"onlineMessagePlaceholder":"Type message here...",
"whiteLabel":false,
"trackPresence":false,
"offlineGreeting":"Sorry we are away, but we would love to hear from you and chat soon!",
"offlineEmailPlaceholder":"Email",
"offlineMessagePlaceholder":"Your message here",
"offlineNamePlaceholder":"Name (optional but helpful)",
"offlineSendButton":"Send",
"offlineThankYouMessage":"Thanks for your message. We will be in touch soon!",
"requireInfo":false,
"requireInfoGreeting":"Enter your name and email to start chatting!",
"requireInfoSubmitBtn":"Start",
"requestScreenshotText":"Operator would like to take a screenshot of your browser. Confirm below.",
"requestScreenshotAllowLabel":"Take screenshot",
"requestScreenshotDeclineLabel":"Decline",
"teamAvatarOn":false,
"collapsedMode":"chip",
"defaultOkBtnLabel":"Ok",
"defaultSendBtnLabel":"Send",
"defaultCancelBtnLabel":"Cancel",
"defaultYesBtnLabel":"Yes",
"defaultNoBtnLabel":"No",
"showConversationEnd":true,
"showConversationRating":true,
"showTranscriptSendOpt":true,
"clearMessagesOnEnd":false,
"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",
"blacklistedUrls":"",
"triggerJson":"",
"useSgmt":false,
"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 https://api-cdn.chatlio.com/v1/p/chat_endpoints/[your widget id]
You can configure the time-related strings Chatlio uses in the messages list to your locale like this:
_chatlio.configure({
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.
Example:
_chatlio.visitorCountryCode()
"US"
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.
Example:
_chatlio.reset();
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.
Example:
_chatlio.clearHistory();
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?
Example:
var button = document.querySelectorAll("#some-selector")[0];
button.addEventListener("click", () => {
_chatlio.switchWidget("abc123ab-abc1-234a-bcd1-234abcd123ab");
});
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.
Example:
_chatlio.send("This message is sent programmatically");
NOTE: _chatlio.send() will not work if the Chatlio widget has not been rendered (e.g. if you are using the data-start-hidden attribute and have not called _chatlio.show() yet, _chatlio.send() will do nothing). If you want to send a message in this situation, use _chatlio.show().send("hello world").
_chatlio.messages()
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 data-start-hidden attribute to your embed code as seen below, this forces the widget to stay hidden until your own code summons it.
<chatlio-widget data-start-hidden widgetid="<your widget ID here>"></chatlio-widget>
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) {
_chatlio.show()
}
});
</script>
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 _chatlio.page() 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:
_chatlio.page();
Programattically fire “triggered” messages. Chatlio does have a built-in trigger feature that can be used instead.
Assuming you have your own logic for a shouldShowTriggerHere() function, see following example.
if (shouldShowTriggerHere()) {
_chatlio.trigger({message: "Help is available!", after: 0});
}
NOTE: Triggers will not be shown on mobile devices due to the lack of screen space. Triggers with an uid that has been seen before by visitor will not be shown. Also, you can only fire one trigger per hour for each visitor.
_chatlio.trigger() takes the following arguments.
{
message: "automessage text here",
after: 30, // seconds,
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)
_chatlio.fullScreen();
// probably don't need this option, but in case you do.
setTimeout(function(){
console.log("disable full screen after 5secs");
// disable full screen when expanded
_chatlio.exitFullScreen();
},5000);
}
}, false);
If desired, you can prevent Chatlio from using cookies to store visitor session data by adding the data-chatlio-cookies attribute to your embed code <chatlio-widget> element like below.
<chatlio-widget data-disable-cookies widgetid="<your widget ID here>"></chatlio-widget>
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 chatlio-widget element by adding the data-chatlio-debug attribute.
<chatlio-widget data-chatlio-debug widgetid="<your widget ID here>"></chatlio-widget>
To turn it on temporarily, you can utilize the configure() method as seen below:
_chatlio.configure({debug: true});
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