Skip to content
SupportOS
Back to Docs

Widget Reference

Full configuration reference for the SupportOS embeddable chat widget.

Basic Installation

Add the following script tag to your website, just before the closing </body> tag:

<script
  src="https://support-app.blueforge.studio/widget.js"
  data-workspace-id="YOUR_WORKSPACE_ID"
  data-accent-color="#2563eb"
  data-position="bottom-right"
  data-greeting="Hi there! How can we help?"
  async
></script>

Data Attributes

Configure the widget via HTML data attributes on the script tag.

AttributeRequiredTypeDescription
data-workspace-idYesstringYour workspace ID. Found in Settings > Widget in your dashboard.
data-api-urlNostringCustom API base URL. Defaults to https://support-app.blueforge.studio. Only needed for self-hosted deployments.
data-accent-colorNostringHex color for the widget button and header. Defaults to #18181b (zinc-900). Example: #2563eb for blue.
data-positionNo"bottom-right" | "bottom-left"Widget button position. Defaults to bottom-right.
data-greetingNostringInitial greeting message shown when the widget opens. Defaults to "Hi there! How can we help?"
data-titleNostringHeader title shown in the widget. Defaults to your workspace name.

JavaScript API

The widget exposes a global SupportOS object for programmatic control.

SupportOS.init(config)

Manually initialize the widget with a config object. Only needed if you omit the data attributes from the script tag.

SupportOS.init({
  workspaceId: 'ws_abc123',
  accentColor: '#2563eb',
  position: 'bottom-right',
  greeting: 'Welcome! Ask us anything.',
  title: 'Acme Support',
});

SupportOS.open()

Programmatically open the chat widget.

document.querySelector('#help-btn')
  .addEventListener('click', () => {
    SupportOS.open();
  });

SupportOS.close()

Programmatically close the chat widget.

SupportOS.close();

SupportOS.destroy()

Remove the widget from the DOM and clean up event listeners. Useful for SPAs when navigating away from support pages.

// On route change
SupportOS.destroy();

SupportOS.setConfig(config)

Update widget configuration at runtime. Accepts a partial config object — only the provided keys are updated.

SupportOS.setConfig({
  accentColor: '#16a34a',
  greeting: 'Need help with your order?',
});

React / Next.js Integration

For React and Next.js apps, use the Script component or a custom wrapper:

// app/layout.tsx (Next.js App Router)
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://support-app.blueforge.studio/widget.js"
          data-workspace-id="YOUR_WORKSPACE_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

If you need programmatic control, create a wrapper component:

'use client';

import { useEffect } from 'react';

declare global {
  interface Window {
    SupportOS: {
      init: (config: Record<string, string>) => void;
      open: () => void;
      close: () => void;
      destroy: () => void;
      setConfig: (config: Record<string, string>) => void;
    };
  }
}

export function SupportOSWidget({
  workspaceId,
}: {
  workspaceId: string;
}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://support-app.blueforge.studio/widget.js';
    script.dataset.workspaceId = workspaceId;
    script.async = true;
    document.body.appendChild(script);

    return () => {
      window.SupportOS?.destroy();
      script.remove();
    };
  }, [workspaceId]);

  return null;
}

Styling Customization

The widget renders inside a shadow DOM to avoid CSS conflicts with your site. You can customize colors using the data-accent-color attribute or the setConfig API.

// Change accent color at runtime
SupportOS.setConfig({
  accentColor: '#7c3aed', // violet
});

// Match user's preferred color scheme
const isDark = window.matchMedia(
  '(prefers-color-scheme: dark)'
).matches;
SupportOS.setConfig({
  accentColor: isDark ? '#e4e4e7' : '#18181b',
});

The accent color is applied to the widget button, header background, and primary action buttons. All other colors are derived automatically from the accent.

← QuickstartAPI Reference →