NAV Navbar
  • Introduction
  • Visitor Identification
  • Contact Properties
  • Listeners / Events
  • Automation events
  • Other methods
  • Code snippets
  • 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

      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

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

    The events are as follows: setStatus, messageFromOperator, messageFromVisitor, conversationStart, preFormFilled, resize, open, close.

    conversationStart will trigger on the first message from visitor which wasn't handled by an automation. Event can trigger again for the same visitor if his/her last message is older than 1 day.

    Automation events


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

    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.


    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


    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


    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.

    <a href="#" onclick="">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 = "//";
    }, 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() {;
      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.