Embed Widget Guide

Learn how to add your chat widget to any website

Our widget uses advanced iframe isolation technology - the same approach used by LiveChat, Intercom, and Drift. This ensures zero CSS conflicts and maximum compatibility with any website.

Getting Your Embed Code

To get your widget's embed code:

Open your widget in the editor
Click the "Get Code" button in the top navigation
Copy the embed code provided
Paste it into your website's HTML

Example Embed Codehtml

<script
  src="https://yoursite.com/embed/widget.js"
  data-widget-id="your-widget-id"
  data-supabase-url="https://your-project.supabase.co"
  data-supabase-key="your-anon-key"
  defer>
</script>

Installation Methods

Basic HTML Website

For a standard HTML website, add the embed code just before the closing </body> tag:

HTML Implementationhtml

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
</head>
<body>
  <!-- Your website content -->
  <h1>Welcome to My Website</h1>

  <!-- ChatWidgetPro embed code -->
  <script
    src="https://yoursite.com/embed/widget.js"
    data-widget-id="your-widget-id"
    data-supabase-url="https://your-project.supabase.co"
    data-supabase-key="your-anon-key"
    defer>
  </script>
</body>
</html>

WordPress

To add the widget to a WordPress site:

Go to Appearance → Theme Editor
Find the footer.php file
Paste the embed code before </body>
Save the file

Alternatively, use a plugin like "Insert Headers and Footers" to add the code without editing theme files.

Shopify

To add the widget to your Shopify store:

Go to Online Store → Themes
Click "Actions" → "Edit code"
Find the theme.liquid file
Paste the embed code before </body>
Click "Save"

React Application

For React apps, add the script in your public/index.html or use a useEffect hook:

React Implementationjsx

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://yoursite.com/embed/widget.js';
    script.setAttribute('data-widget-id', 'your-widget-id');
    script.setAttribute('data-supabase-url', 'https://your-project.supabase.co');
    script.setAttribute('data-supabase-key', 'your-anon-key');
    script.defer = true;
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return <div>Your App</div>;
}

Next.js Application

For Next.js, use the Script component in your _app.js or layout:

Next.js Implementationjsx

import Script from 'next/script';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <Script
        src="https://yoursite.com/embed/widget.js"
        data-widget-id="your-widget-id"
        data-supabase-url="https://your-project.supabase.co"
        data-supabase-key="your-anon-key"
        strategy="lazyOnload"
      />
    </>
  );
}

Configuration Options

You can customize the widget's behavior using data attributes on the script tag:

data-widget-id

Required. Your unique widget ID.

data-widget-id="abc123"

data-supabase-url

Required. Your Supabase project URL.

data-supabase-url="https://your-project.supabase.co"

data-supabase-key

Required. Your Supabase anonymous key.

data-supabase-key="your-anon-key"

data-position

Optional. Widget position on screen. Default: "right"

data-position="left" | "right"

Widget Positioning

The widget's position is configured in the editor's Bubble tab. You can set:

Right position (distance from right edge)
Bottom position (distance from bottom edge)

For inline widgets, the position settings don't apply. The widget appears wherever you place the script tag in your HTML.

Multiple Widgets

You can add multiple widgets to the same page by including multiple script tags with different widget IDs:

Multiple Widgetshtml

<!-- Support widget -->
<script
  src="https://yoursite.com/embed/widget.js"
  data-widget-id="support-widget-id"
  defer>
</script>

<!-- Sales widget -->
<script
  src="https://yoursite.com/embed/widget.js"
  data-widget-id="sales-widget-id"
  defer>
</script>

Make sure each widget has different positioning to avoid overlapping bubbles.

Conditional Loading

Load on Specific Pages

You may want to show the widget only on certain pages. Here are some approaches:

WordPress Conditionalhtml

<?php if (is_page('contact')): ?>
  <script
    src="https://yoursite.com/embed/widget.js"
    data-widget-id="your-widget-id"
    defer>
  </script>
<?php endif; ?>

Load Based on User Status

Load different widgets for logged-in vs. logged-out users:

React Conditional Loadingjsx

function App() {
  const { user } = useAuth();

  useEffect(() => {
    const widgetId = user
      ? 'logged-in-widget-id'
      : 'guest-widget-id';

    const script = document.createElement('script');
    script.src = 'https://yoursite.com/embed/widget.js';
    script.setAttribute('data-widget-id', widgetId);
    script.defer = true;
    document.body.appendChild(script);

    return () => document.body.removeChild(script);
  }, [user]);
}

Performance Optimization

Lazy Loading

The widget script includes the "defer" attribute by default, which ensures it doesn't block page rendering. For even better performance:

Place the script at the end of the body
Use async loading if the widget isn't critical
Consider delaying the widget load until user interaction

Load on User Interaction

Load the widget only when the user scrolls or clicks:

Delayed Loadingjavascript

let widgetLoaded = false;

function loadWidget() {
  if (widgetLoaded) return;

  const script = document.createElement('script');
  script.src = 'https://yoursite.com/embed/widget.js';
  script.setAttribute('data-widget-id', 'your-widget-id');
  script.defer = true;
  document.body.appendChild(script);

  widgetLoaded = true;
}

// Load on scroll
window.addEventListener('scroll', loadWidget, { once: true });

// Or load after 3 seconds
setTimeout(loadWidget, 3000);

Architecture Benefits

Our widget uses an iframe-based architecture that provides several important benefits:

Zero CSS Conflicts

Widget styles are completely isolated in an iframe. Your site's CSS cannot affect the widget, and the widget's CSS cannot affect your site.

Maximum Z-Index

The widget always appears on top with z-index 2147483647 (maximum value), so it won't be hidden by other page elements.

Lightweight Loader

The initial script is under 7KB. The full widget loads in the background inside the iframe without blocking your page.

Cross-Browser Compatible

Works flawlessly on all modern browsers including Chrome, Firefox, Safari, Edge, and mobile browsers.

Troubleshooting

Widget Not Appearing

Check that the script tag is correctly formatted
Verify the widget ID is correct
Open browser console and look for error messages
Ensure the script URL is accessible
Check that your widget is published
Verify your domain is in the allowed domains list (if configured)

Widget Not Responding

Verify your webhook URL is correct in the widget settings
Check browser console for network errors
Test your webhook independently
Ensure CORS is properly configured on your backend

Styling Issues

With our iframe architecture, CSS conflicts are virtually eliminated. The widget runs in complete isolation.

Adjust positioning in the widget editor if needed
Test on different screen sizes and devices
Check if any browser extensions might interfere

Best Practices

Test before deploying: Always test the widget on a staging site first
Mobile optimization: Test the widget on mobile devices
Monitor performance: Check page load times with the widget
Keep it updated: Update the embed code when you update widget settings
Use analytics: Monitor widget usage from your dashboard
Provide fallbacks: Ensure users can still contact you if the widget fails

Need Integration Help?

Check out our platform-specific integration guides or contact support.

Integration Guides Go to Dashboard