TidySupport logo
TidySupport logo

  1. Home

    2. /

  2. Docs

    3. /

  3. API Reference

    4. /

  4. Widget

Widget Installation

The TidySupport widget adds a live chat interface to your website. Visitors can start conversations, receive AI-powered responses, and reach your support team directly. The widget supports authenticated and anonymous visitors, file attachments, email collection, and full customization.

Quick Start

Add this script tag to your website, just before the closing </body> tag. Replace the publishable key with your own from Settings > Integrations > API in your dashboard.

<script
  src="https://api.tidysupport.com/embeds/v1/support-widget.js"
  data-publishable-key="pk_live_YOUR_KEY_HERE"
  async
  defer
></script>

That's it. The widget will appear as a chat button in the bottom-right corner of your page.

Script Tag Attributes

Configure the widget using data-* attributes on the script tag:

data-publishable-keystringrequired
Your workspace publishable key (starts with pk_). Found in Settings > Integrations > API.
data-user-emailstring
Pre-fill the visitor email. Useful when the user is already logged in to your app.
data-user-namestring
Pre-fill the visitor display name.
data-signaturestring
HMAC-SHA256 signature for authenticated visitors. See Identity Verification below.
data-visitor-idstring
Custom visitor identifier. Auto-generated if not provided.
data-alignstring
Widget position: "left" or "right" (default: "right").
data-localestring
Language/locale preference for widget text.

Example with pre-filled user data

<script
  src="https://api.tidysupport.com/embeds/v1/support-widget.js"
  data-publishable-key="pk_live_YOUR_KEY_HERE"
  data-user-email="jane@example.com"
  data-user-name="Jane Doe"
  data-align="right"
  async
  defer
></script>

JavaScript API

For more control, use the JavaScript API instead of (or in addition to) data attributes. You can queue commands before the script loads.

Queue pattern (recommended)

<script>
  // Initialize the command queue before the widget script loads
  window.TidySupport = window.TidySupport || function() {
    (window.TidySupport.q = window.TidySupport.q || []).push(arguments);
  };
  window.TidySupport.q = window.TidySupport.q || [];

  // Queue commands — these run after the widget loads
  window.TidySupport('boot', {
    publishableKey: 'pk_live_YOUR_KEY_HERE',
    email: 'jane@example.com',
    name: 'Jane Doe'
  });
</script>

<!-- Load the widget script -->
<script
  src="https://api.tidysupport.com/embeds/v1/support-widget.js"
  async
  defer
></script>

Available commands

bootconfig object
Initialize the widget with publishableKey, email, name, signature, visitorId, and locale.
shutdownnone
Remove the widget and clean up all resources.
open{ message?, autoSend? }
Open the chat panel. Optionally pre-fill a message and auto-send it.
closenone
Close the chat panel.
shownone
Show the chat button (if hidden).
hidenone
Hide the chat button.
identify{ email?, name?, visitorId?, signature? }
Update the visitor identity after initialization.
trackEventname, properties
Track a custom event for the visitor.
trackPageviewnone
Track a page view. Called automatically on SPA route changes.

Command examples

// Open the chat panel
window.TidySupport('open');

// Open with a pre-filled message
window.TidySupport('open', {
  message: 'I need help with billing',
  autoSend: false
});

// Update visitor identity (e.g., after login)
window.TidySupport('identify', {
  email: 'jane@example.com',
  name: 'Jane Doe'
});

// Hide the widget on specific pages
window.TidySupport('hide');

// Track a custom event
window.TidySupport('trackEvent', 'plan_upgraded', {
  plan: 'pro',
  amount: 29
});

// Remove the widget completely
window.TidySupport('shutdown');

Identity Verification

Identity verification uses HMAC-SHA256 signatures to securely associate widget sessions with known contacts. This prevents impersonation and ensures conversation history is linked to the correct customer.

Important: Generate signatures on your server, never in client-side code. Your signing secret must stay private.

Step 1: Generate the signature on your server

const crypto = require('crypto');

function generateWidgetSignature(signingSecret, visitorId, email) {
  const payload = visitorId + ':' + (email || '').toLowerCase();
  return crypto
    .createHmac('sha256', signingSecret)
    .update(payload)
    .digest('hex');
}

// Example usage in an Express endpoint
app.get('/api/widget-signature', (req, res) => {
  const signature = generateWidgetSignature(
    process.env.TIDYSUPPORT_SIGNING_SECRET,
    req.query.visitorId,
    req.user.email
  );
  res.json({ signature });
});

Step 2: Pass the signature to the widget

<script>
  window.TidySupport = window.TidySupport || function() {
    (window.TidySupport.q = window.TidySupport.q || []).push(arguments);
  };
  window.TidySupport.q = window.TidySupport.q || [];

  // Fetch signature from your backend
  fetch('/api/widget-signature?visitorId=vis_abc123')
    .then(res => res.json())
    .then(({ signature }) => {
      window.TidySupport('boot', {
        publishableKey: 'pk_live_YOUR_KEY_HERE',
        visitorId: 'vis_abc123',
        email: 'jane@example.com',
        name: 'Jane Doe',
        signature: signature
      });
    });
</script>

<script
  src="https://api.tidysupport.com/embeds/v1/support-widget.js"
  async
  defer
></script>

Tip: You can find your signing secret in Settings > Widget > Identity Verification in your dashboard. The signature format is HMAC-SHA256(signingSecret, visitorId:email).

React / SPA Installation

For React, Next.js, or other single-page applications, install the SDK package and initialize programmatically.

Install the package

npm install @tidysupport/ui

Initialize in your app

import { useEffect } from 'react';
import { initSupportWidget } from '@tidysupport/ui';

function App() {
  useEffect(() => {
    const client = initSupportWidget({
      publishableKey: 'pk_live_YOUR_KEY_HERE',
      identity: {
        email: user.email,
        name: user.name,
        signature: userSignature, // from your backend
      },
    });

    client.mount();

    return () => {
      client.unmount();
    };
  }, []);

  return <div>{/* Your app */}</div>;
}

Widget Customization

Customize the widget appearance from Settings > Widget in your dashboard. Available options include:

Brand Namestring
Display name shown in the widget header (default: "Support")
Primary Colorhex color
Button and accent color used throughout the widget
Background Colorhex color
Chat panel background color
Alignment"left" | "right"
Which side of the screen the widget appears on
Button Stylepreset
Choose from 16 button designs: classic, pill, glass, holographic, square, rounded-square, ring, gradient, floating, minimal, neon, shadow-pop, soft, bounce, diamond, and more
Button Animationpreset
Optional entrance animation: none, pulse, bounce, shake, breathe, or spin-in
Email Collectionsetting
When to prompt for email: before first message, after first message, or after second message. Toggle "Require email" on or off.
File Attachmentsboolean
Allow visitors to upload files (up to 5 MB per file)
Screenshotsboolean
Allow visitors to capture and send screenshots

Troubleshooting

Widget not appearing

  • Verify your publishable key is correct and starts with pk_
  • Check the browser console for errors
  • Ensure the script tag includes async and defer
  • Confirm your workspace subscription is active

Identity verification failing

  • Ensure the signature is generated server-side using the correct signing secret
  • The signature payload must be visitorId:email (lowercase email)
  • The same visitorId must be passed to both your signing endpoint and the widget boot command

Conversations not linking to contacts

  • Pass the data-user-email attribute or use identify to associate the widget session with a known contact
  • For verified identity linking, implement identity verification with signatures