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
email	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.

NOTE: hiding the chat window through tidioChatApi does not block triggering chatbots.

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.