NAV Navbar
  • Introduction
  • Visitor Identification
  • 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 user ID in your system
      email: "contact_mail", // User email
      name: "John Doe", // Visitor name
      city: "Denver", // City
      country: "US" // Country
    };
    

    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.

    Parameter Description Format
    distinct_id Unique ID in your System for visitor "string"
    email user Email "string"
    country Country "string", iso 3166-1 alfa-2
    city City "string"
    name Visitor name "string"
    postcode Postal code "string"
    phone Phone number "string", area code required, format +44 2032897807

    Updating visitor data

    tidioChatApi.setVisitorData({
      email: "[email protected]",
      tags: ["tag1", "tag2"]
    });
    

    You can update visitor data only after the Tidio Chat code is loaded.

    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.

    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.

    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.

    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.

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