Website Chat Widget

Overview

The Website Chat Widget lets you embed a Spinnable worker directly on your website as a floating chat window. Visitors can ask questions, get support, or interact with your worker — all without leaving your site.

The widget is configured from your worker’s Details → Website Widget section in the Spinnable dashboard. This guide covers the implementation details for embedding and customizing the widget on your website.

Quick Start

Enable the widget

In your worker’s dashboard, go to Details → Website Widget, create a widget key, and configure your allowed domains.

Add the embed code

Copy the embed snippet from the dashboard and paste it into your website’s HTML, just before the closing </body> tag:

<script
  src="https://app.spinnable.com/widget/v1/embed.js"
  data-api-url="https://api.spinnable.com"
  defer
></script>
<spinnable-widget key="wk_xxxxx"></spinnable-widget>

Replace wk_xxxxx with the widget key from your dashboard.

You're live!

The widget appears as a floating chat button in the bottom-right corner of your page. Visitors can click it to start chatting with your worker.

Make sure your website’s domain is added to the Allowed Domains list in the widget settings. The widget will not work on domains that aren’t explicitly allowed.

Visitor Identification

By default, the widget assigns each browser a random anonymous ID stored in localStorage. This means visitors get a fresh identity per device/browser and their sessions are not linked across devices. To provide a better experience — like linking conversations to your own user accounts and letting visitors see their past sessions — you can identify visitors using SpinnableWidget.init().

Anonymous (Default)
Identified Visitor
Identified + Profile

When no visitor identification is provided, the widget automatically:

Generates a unique ID per browser and stores it in localStorage
Sessions are tied to that browser only
If the visitor clears their browser data, their history is lost

No code changes needed — this is the default behavior.

To tie conversations to your own user system, call SpinnableWidget.init() with a visitorId:

<script>
  window.SpinnableWidget = window.SpinnableWidget || {};
  window.SpinnableWidget.init = window.SpinnableWidget.init || function(opts) {
    window._spinnableWidgetInit = opts;
  };
</script>

<script
  src="https://app.spinnable.com/widget/v1/embed.js"
  data-api-url="https://api.spinnable.com"
  defer
></script>
<spinnable-widget key="wk_xxxxx"></spinnable-widget>

<script>
  SpinnableWidget.init({
    visitorId: "user-12345"
  });
</script>

When you provide a visitorId:

Sessions persist across devices — the same visitor sees their full conversation history wherever they log in
Conversations are linked to your internal user ID
The visitor ID can be any non-empty string — all values are normalized to a deterministic UUID scoped to your worker, so the same ID on different workers yields different internal IDs

Use the same user ID from your own authentication system as the visitorId. This makes it easy to link widget conversations with your existing user records.

You can optionally include profile information that will appear in Spinnable’s Oversight panel and be available to your worker:

<script>
  window.SpinnableWidget = window.SpinnableWidget || {};
  window.SpinnableWidget.init = window.SpinnableWidget.init || function(opts) {
    window._spinnableWidgetInit = opts;
  };
</script>

<script
  src="https://app.spinnable.com/widget/v1/embed.js"
  data-api-url="https://api.spinnable.com"
  defer
></script>
<spinnable-widget key="wk_xxxxx"></spinnable-widget>

<script>
  SpinnableWidget.init({
    visitorId: "user-12345",
    visitor: {
      name: "Jane Smith",
      email: "jane@example.com",
      phone_number: "+1234567890"
    }
  });
</script>

Field	Type	Description
`name`	string	Visitor’s display name
`email`	string	Visitor’s email address
`phone_number`	string	Visitor’s phone number

Only name, email, and phone_number are supported. Custom metadata is not passed to the worker.

Use the same user ID from your own authentication system as the visitorId. This makes it easy to link widget conversations with your existing user records.

Profile information is sent with the first message in each session. It helps your worker provide personalized responses and shows visitor details in the Oversight panel.

About the init polyfill

You’ll notice the init snippet includes a small “polyfill” block before the widget script:

<script>
  window.SpinnableWidget = window.SpinnableWidget || {};
  window.SpinnableWidget.init = window.SpinnableWidget.init || function(opts) {
    window._spinnableWidgetInit = opts;
  };
</script>

This ensures SpinnableWidget.init() can be called before the widget script finishes loading. The widget script loads with defer, so this polyfill safely stores your configuration until the widget is ready to pick it up. You can place SpinnableWidget.init() anywhere on the page — before or after the widget script.

Session Management

The widget supports multiple conversation sessions per visitor:

New visitors see an intro panel with a welcome message and suggested prompts (configured in the dashboard)
Returning visitors (identified via visitorId) see a list of their past sessions and can:
- Open any previous conversation to continue it
- Start a new conversation with the New Chat button
The current session is persisted in localStorage and survives page refreshes

Theming & Customization

Via the Dashboard

The primary way to customize the widget’s appearance is through the Styling tab in Details → Website Widget. You can configure:

Panel title — the header text shown at the top of the widget
Theme colors — primary, background, foreground, and text colors
Intro panel — heading, description, and suggested prompt buttons
Input placeholder — the placeholder text in the message input
Launcher icon — choose between chat, help, or support icons
Launcher position — bottom-right or bottom-left

Via JavaScript (Per-Page Overrides)

For advanced use cases — like matching different themes on different pages — you can override the dashboard config by passing a theme object to SpinnableWidget.init():

<script>
  SpinnableWidget.init({
    visitorId: "user-12345",
    theme: {
      primary: "#0066cc",
      primaryForeground: "#ffffff",
      background: "#f8fafc",
      foreground: "#1e293b"
    }
  });
</script>

JavaScript overrides take priority over dashboard settings. This lets you use the dashboard as a default while customizing specific pages as needed.

All available theme properties

Property	Description	Default
`primary`	Buttons, header, user message bubbles, launcher	Emerald green
`primaryForeground`	Text on primary-colored elements	White
`background`	Widget panel background	White
`foreground`	Main text color	Dark gray
`border`	Borders and dividers	Light gray
`muted`	Muted UI elements	Slate
`mutedForeground`	Secondary text (empty states, descriptions)	Slate
`errorBg`	Error state background	Light red
`errorText`	Error state text	Dark red
`fontFamily`	Font stack	`Inter, system-ui, sans-serif`
`borderRadius`	Panel corner radius	`12px`
`borderRadiusSm`	Input and button corner radius	`8px`

Allowed Domains & Security

The widget uses your Widget Key and Origin validation to ensure only authorized websites can embed your worker:

Every request from the widget includes the X-Widget-Key header and the browser’s Origin header
The backend validates both against your configuration
Wildcard domains are supported (e.g., https://*.acme.com matches all subdomains)

If you see a 403 error in the widget, your website’s domain is not in the allowed list. Add it in Details → Website Widget → Allowed Domains.

Key Regeneration

If you suspect your widget key has been compromised, you can regenerate it from the dashboard:

A new key is issued immediately
The old key remains valid for 24 hours (grace period) so you have time to update your embed code
After 24 hours, the old key stops working

Action Modes

When creating a widget key, you choose an action mode that controls what your worker can do when responding to widget visitors:

Mode	Description
Guest (recommended)	Read-only interactions — safest for public websites
Collaborator	Limited access — can read and contribute but not manage
Org Member	Can read and contribute with broader permissions
Owner	Full access — use with caution on public sites

For public-facing websites, we strongly recommend using Guest mode to minimize risk. Only use higher permission levels if your widget is on an authenticated internal tool.

File Uploads

The widget supports file uploads from visitors:

Maximum 3 files per message
Maximum 5 MB per file
Drag-and-drop is supported

Troubleshooting

Widget shows a 403 error

Widget shows a 401 error

Widget doesn't appear on the page

Visitor sessions are not persisting across devices

If you’re using the default anonymous mode, sessions are tied to localStorage — they only exist in that specific browser. For cross-device persistence, implement Visitor Identification with a consistent visitorId from your user system.

Theme changes aren't showing

A few things to check:

Dashboard theme changes apply on the next widget load — refresh the page
JavaScript overrides via SpinnableWidget.init() take priority over dashboard settings
Ensure color values are valid CSS (hex, HSL, or named colors)

Full Example

Here’s a complete implementation with visitor identification, profile data, and custom theming:

<!-- Polyfill: allows SpinnableWidget.init() to be called before the script loads -->
<script>
  window.SpinnableWidget = window.SpinnableWidget || {};
  window.SpinnableWidget.init = window.SpinnableWidget.init || function(opts) {
    window._spinnableWidgetInit = opts;
  };
</script>

<!-- Widget script -->
<script
  src="https://app.spinnable.com/widget/v1/embed.js"
  data-api-url="https://api.spinnable.com"
  defer
></script>

<!-- Widget element -->
<spinnable-widget key="wk_xxxxx"></spinnable-widget>

<!-- Initialize with visitor data and theme -->
<script>
  SpinnableWidget.init({
    visitorId: "user-12345",
    visitor: {
      name: "Jane Smith",
      email: "jane@example.com",
      phone_number: "+1234567890"
    },
    theme: {
      primary: "#6366f1",
      primaryForeground: "#ffffff",
      background: "#ffffff",
      foreground: "#1e293b"
    }
  });
</script>

Getting Started

Core Concepts

Common Tasks

Account & Billing

Troubleshooting

Support

Overview

Quick Start

Visitor Identification

About the init polyfill

Session Management

Theming & Customization

Via the Dashboard

Via JavaScript (Per-Page Overrides)

Allowed Domains & Security

Key Regeneration

Action Modes

File Uploads

Troubleshooting

Full Example

Next Steps

Communication Channels

Security Best Practices

Getting Started

Core Concepts

Common Tasks

Account & Billing

Troubleshooting

Support

​Overview

​Quick Start

​Visitor Identification

​About the init polyfill

​Session Management

​Theming & Customization

​Via the Dashboard

​Via JavaScript (Per-Page Overrides)

​Allowed Domains & Security

​Key Regeneration

​Action Modes

​File Uploads

​Troubleshooting

​Full Example

​Next Steps

Communication Channels

Security Best Practices

Overview

Quick Start

Visitor Identification

About the init polyfill

Session Management

Theming & Customization

Via the Dashboard

Via JavaScript (Per-Page Overrides)

Allowed Domains & Security

Key Regeneration

Action Modes

File Uploads

Troubleshooting

Full Example

Next Steps