Suppabot
Suppabot/Docs

Widget Integration

Technical guide for embedding and configuring the Suppabot widget on any website or framework.

Widget Integration

This guide covers the technical details of embedding the Suppabot chat widget, including framework-specific installation, SPA behavior, CSP configuration, and domain restrictions.

Standard embed

The simplest installation is a single script tag placed before the closing </body> tag:

<script src="https://suppabot.com/widget.js?key=YOUR_WIDGET_KEY" defer></script>

The script loads asynchronously (defer), does not block page rendering, and injects the widget launcher into the DOM when the page is ready.

Finding your widget key: Go to Dashboard → your website → Appearance and click Copy Embed Code. Each website in your Suppabot account has a unique key.

Next.js (App Router)

Use the built-in Script component with strategy="afterInteractive". This ensures the widget loads after Next.js hydrates the page:

// src/app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://suppabot.com/widget.js?key=YOUR_WIDGET_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Adding the script to your root layout.tsx means it loads on every route automatically.

Next.js (Pages Router)

In _app.tsx, use next/script in the same way:

// src/pages/_app.tsx
import type { AppProps } from "next/app";
import Script from "next/script";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://suppabot.com/widget.js?key=YOUR_WIDGET_KEY"
        strategy="afterInteractive"
      />
    </>
  );
}

React (Vite or Create React App)

Inject the script on mount using useEffect in your root component:

// src/main.tsx or src/App.tsx
import { useEffect } from "react";

function App() {
  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://suppabot.com/widget.js?key=YOUR_WIDGET_KEY";
    script.defer = true;
    document.body.appendChild(script);
  }, []);

  return <>{/* your app */}</>;
}

The empty dependency array ensures the script is injected exactly once.

Google Tag Manager

  1. In your GTM workspace, go to Tags → New.
  2. Click Tag Configuration → Custom HTML.
  3. Paste the following: 
    <script src="https://suppabot.com/widget.js?key=YOUR_WIDGET_KEY" defer></script>
  4. Under Triggering, select All Pages.
  5. Name the tag (e.g. Suppabot Widget) and click Save.
  6. Click Submit to publish the container.

Single-page applications (SPAs)

The Suppabot widget persists across SPA route changes automatically. The script only needs to be loaded once — it listens for browser history events and keeps the widget visible as the user navigates through your app.

Do not re-inject the script on route changes, as this will create duplicate widget instances.

Content Security Policy (CSP)

If your site sets a Content-Security-Policy header, add the following directives to allow the Suppabot widget to load and function:

script-src 'self' https://suppabot.com;
connect-src 'self' https://suppabot.com;
frame-src 'self' https://suppabot.com;
img-src 'self' https://suppabot.com data:;

If you use a nonce-based CSP, contact Suppabot support for nonce-compatible embedding instructions.

Allowed domains

By default, your widget key works on any domain. This is convenient for development and staging environments, but you should restrict it in production to prevent your key from being used on unauthorized sites.

To restrict your widget key to specific domains:

  1. Go to Dashboard → your website → Settings → Allowed Domains.
  2. Add each domain where the widget is permitted to load (e.g. yourcompany.com, www.yourcompany.com).
  3. Click Save.

The widget will silently fail to initialize on any domain not in this list. Keep localhost in the list during development.

Verifying installation

Open your site in a browser, open DevTools, and check:

  • Network tab: You should see a request to suppabot.com/widget.js.
  • Elements tab: Search for suppabot — a widget container element should be present in the DOM.
  • Console tab: No errors related to Suppabot should appear.

If the widget does not appear:

  1. Confirm the script tag is present in the rendered HTML (not just your source template).
  2. Confirm the widget key matches the one in your dashboard.
  3. Confirm your domain is on the allowed domains list (if configured).
  4. Check for CSP violations in the Console.
← PreviousPlans & BillingNext →Webhooks