Tidio Widget SDK

Control the chat widget from your own JavaScript — on any plan

Tidio's Widget SDK is a JavaScript API that lets you programmatically interact with the Tidio chat widget embedded on your site. Unlike the REST API (which requires the Plus plan — contact sales for current pricing), the Widget SDK is available on all plans, including free.

What the SDK can do

The SDK exposes the tidioChatApi object on the window, giving you control over:

• Open and close the widget — trigger the chat window based on user actions
• Identify visitors — pass user email, name, and custom attributes to Tidio
• Set custom properties — attach metadata to visitors for segmentation and routing
• Trigger Flows — start specific chatbot automations programmatically
• Listen for events — react to widget state changes (open, close, new message)
• Pre-chat data — populate fields before the visitor starts typing
• Hide or show the widget — control visibility based on page context

How to access it

The SDK becomes available after the Tidio script loads on your page. Since the script loads asynchronously, you need to wait for it:

document.addEventListener("tidioChat-ready", function () {
  // tidioChatApi is now available
  window.tidioChatApi.open();
});

If you're working in a single-page app (React, Vue, etc.), attach the event listener early in your app lifecycle — typically in a root component's mount hook.

Common use cases with examples

Open chat on button click

document.getElementById("help-btn").addEventListener("click", function () {
  window.tidioChatApi.open();
});

Identify a logged-in user

document.addEventListener("tidioChat-ready", function () {
  window.tidioChatApi.setVisitorData({
    distinct_id: "user_12345",
    email: "jane@example.com",
    name: "Jane Doe",
  });
});

Pass custom properties

window.tidioChatApi.setContactProperties({
  plan: "premium",
  signup_date: "2026-01-15",
  order_count: 12,
});

Trigger a specific Flow

window.tidioChatApi.trigger("welcome-returning-customer");

Listen for events

document.addEventListener("tidioChat-open", function () {
  console.log("Chat widget opened");
});

document.addEventListener("tidioChat-close", function () {
  console.log("Chat widget closed");
});

document.addEventListener("tidioChat-messageFromVisitor", function (data) {
  console.log("Visitor sent a message");
});

Hide the widget on specific pages

document.addEventListener("tidioChat-ready", function () {
  if (window.location.pathname.startsWith("/checkout")) {
    window.tidioChatApi.hide();
  }
});

Tips

• Always wait for tidioChat-ready. Calling tidioChatApi before the script loads will throw errors.
• Use setVisitorData early. Pass identity data as soon as you know who the visitor is — this ensures conversation history and properties attach to the right contact.
• Test in staging first. Flow triggers and property updates affect live data. Use a test project or sandbox if available.
• Don't over-trigger. Opening the widget automatically on every page load is a common mistake that annoys visitors. Use it selectively.
• Check Tidio's docs for the latest methods. The SDK evolves, and new methods get added with platform updates.

Limitations

• Client-side only — the SDK runs in the browser, so it can't be used for server-side operations
• Widget scope — it controls the chat widget, not the broader Tidio platform (for that, you need the REST API)
• No offline support — requires the Tidio script to be loaded and connected
• No direct Lyro control — you can trigger Flows that invoke Lyro, but you can't configure AI behavior through the SDK

SDK vs. REST API

Most teams start with the SDK and only move to the REST API if they have backend integration requirements that the SDK can't cover.

More developer resources

• Tidio API — REST endpoints for server-side access
• Developers overview — all developer tools and resources

Last updated: April 2026. Based on Tidio's developer documentation and SDK reference.