Introduction
To be able to use the API, you just need to insert Tidio Chat code into your website. You don't need any external libraries.
Visitor Identification
Thanks to Visitor Identification, you'll be able to connect the data from your system with Tidio Chat.
Defining visitor data
document.tidioIdentify = {
distinct_id: "unique_id", // Unique visitor ID in your system
email: "[email protected]", // visitor email
name: "John Doe", // Visitor name
phone: "+44 2032897807" //Visitor phone
};
To define visitor details while loading the page, you need to paste in the JavaScript code from below, just before the chat code. This will fetch the user details from your system and fill them in Tidio Chat.
This function can merge the conversations with the same visitor in the admin panel.
All fields are optional.
Parameter | Description | Format |
---|---|---|
distinct_id | Unique ID in your System for visitor | "string" or number |
user Email | "string", email format required | |
name | Visitor name | "string" |
phone | Phone number | "string", area code required, format +44 2032897807 |
Updating visitor data
tidioChatApi.setVisitorData({
email: "[email protected]",
city: "Denver",
country: "US",
tags: ["tag1", "tag2"]
});
You can update visitor data only after the Tidio Chat code is loaded.
This function won’t merge the conversations with the same visitor in the admin panel.
Remember! If the email defined in document.tidioIdentify will differ from the one triggered through tidioChatApi.setVisitorData, the system will replace the first one after refreshing the page.
tidioChatApi.addVisitorTags(["tag1", "tag2"]);
You can use a separate function to add tags to your visitor. Adding the same tag twice will not duplicate it (tags work as a set - meaning the values are unique).
Contact Properties
Create a contact property and use it to track and store additional information about your contacts (e.g. company name, birthday, or even their favourite colour).
Defining contact properties
To create a new Contact Property, please go to the Settings > Contact Properties section in your Tidio admin panel.
Updating contact properties
tidioChatApi.setContactProperties({
company_name: "Tidio Ltd.",
favourite_feature: "Chatbots"
});
The method is avaiable only for the latest widget version.
You can update contact properties only after the Tidio Chat code is loaded.
Remember! Before updating a new parameter, you must to create a definition of contact property.
Listeners / Events
Fully loading Tidio Chat
(function() {
function onTidioChatApiReady() {
// Code after chat loaded
}
if (window.tidioChatApi) {
window.tidioChatApi.on("ready", onTidioChatApiReady);
} else {
document.addEventListener("tidioChat-ready", onTidioChatApiReady);
}
})();
This function triggers only when Tidio Chat is fully loaded. Once it's up, you'll be able to use the methods below.
Other events
Widget have other events using which you can subscribe with a method.
The methods are as follows: setStatus
, messageFromOperator
, messageFromVisitor
, preFormFilled
, resize
, open
, close
.
Automation events
tidioChatApi.track("eventname");
If you would like to enhance your automations you can add your own events to our API. To enable this, use the following function with the name of your event.
Other methods
A message from an operator
tidioChatApi.messageFromOperator("Message from operator!");
Send a new chat message from a given operator. With this method you are able to send a different automatic message on each page of your website upon your request.
A message from a visitor
tidioChatApi.messageFromVisitor("Message from visitor!");
This method sends a message from the visitor to the operator. This can be used when a visitor clicks on a button on the page. It will then activate a conversation about a certain issue they need help with.
Popup open
tidioChatApi.open();
Opens the chat window. The effect is the same as if a user would click the chat window on your page. If the pre-chat survey is enabled, the visitor will need to fill out the fields before the message sends.
Popup hide
tidioChatApi.close();
This closes the chat window. The effect is the same as when a visitor clicks the X at the top of the chat window.
Chat display
tidioChatApi.display(true);
This will either show or hide the chat window, depending on the setting of the argument. The method is executed asynchronously if it is called upon before loading the chat. When the 'show/hide' function will be called, but before the chat is loaded, then the loading will be postponed until the function with the attribute "true" is ran.
Set Chat Color
tidioChatApi.setColorPalette("#333333");
By using this, you are able to change the colour of the chat. For example, you can adjust the scheme to appear in a unique fashion on each subpage or even set them to appear differently throughout the day or mood.
Code snippets
With snippets below you can extend widget's functionality. Here are a few examples on how to use our Tidio Widget API.
Open chat widget on link click
<a href="#" onclick="tidioChatApi.open()">Open chat!</a>
To do this you need to add an attribute to link as shown in the code below.
Load chat widget after a while
setTimeout(function() {
var tidioScript = document.createElement("script");
tidioScript.src = "//code.tidio.co/PUBLIC_KEY.js";
document.body.appendChild(tidioScript);
}, 5 * 1000);
The script above will allow loading the widget with a certain delay (5 seconds by default).
Open widget after load
(function() {
function onTidioChatApiReady() {
window.tidioChatApi.open();
}
if (window.tidioChatApi) {
window.tidioChatApi.on("ready", onTidioChatApiReady);
} else {
document.addEventListener("tidioChat-ready", onTidioChatApiReady);
}
})();
The script above will make the chat appear fully expanded as soon as it loads on your site.
Widget language
If you have multilanguage site and want to widget match site's langauge you can set it by document.tidioChatLang
property.
Set language from html attribute
document.tidioChatLang = document.querySelector("html").getAttribute("lang");
Script gets language from html lang
attribute and write it to document.tidioChatLang
variable.
Set language with other variable
document.tidioChatLang = "es";
If you want to display chat only in one language or you have it in another place please use the snippet below.