Chat Widget

The Chat Widget lets you embed a CloudStation-powered AI assistant directly on your website. Visitors get a floating chat overlay they can open, drag, and resize — backed by the agent and project you configure.

Overview

The widget appears as a small trigger button (typically in the bottom-right corner) that opens a full chat overlay when clicked. It supports:

Drag and drop — move the trigger button and chat overlay anywhere on screen
Resizable — adjust the overlay width (minimum 420px)
Tab navigation — switch between active Chat and conversation History
Mobile optimized — responsive layout with performance-tuned message rendering
Theme-aware branding — automatically adjusts logo and colors based on your theme settings

How It Works

The widget connects to your CloudStation project through the project's API. When a visitor sends a message, it's routed to the agent assigned in your Project Settings widget configuration. The agent responds in real time via server-sent events (SSE).

Configure in Project Settings

Open your project's settings drawer and expand the Widget Designer section. Choose an agent, set colors, and configure rate limits. See Project Settings — Widget Designer for full details.

Copy the Embed Script

After saving your widget settings, copy the embed snippet from the project settings. Add it to your website's HTML, immediately before </body>:

<script
  src="https://app.cloud-station.io/widgets/chat.js"
  data-widget-id="your-widget-public-id"
  data-api-base-url="https://charlie-back.cloud-station.io"
  data-position="right"
  data-theme="light"
></script>

Your Widget ID is the data-widget-id value inside the generated snippet — there is no separate "Widget ID" field to copy. If data-api-base-url is omitted, the script defaults to https://charlie-back.cloud-station.io.

Go-live checklist for public websites — the two settings that most often break a freshly embedded widget:

Allowed domains must contain your site's exact origin (e.g. https://www.example.com), or the widget shows "Could not load" (the browser blocks the config request with a CORS error).
Require login must be off, or every visitor message fails with "Authentication required" (HTTP 401).

Open your website in a browser. The trigger button should appear. Click it to open the chat overlay and send a test message.

Floating Overlay

The chat opens as a floating overlay (default 560 x 680px) that stays within viewport bounds. Users can:

Drag the trigger button or overlay header to reposition
Resize the overlay width by dragging the left edge
Close with the X button or by clicking the trigger again

The overlay smoothly animates open and closed, and automatically repositions when the browser window resizes.

Chat and History Tabs

The widget has two tabs:

Chat — the active conversation with the AI agent. Supports markdown rendering, clickable links, and real-time streaming responses.
History — browse previous conversations. Click any thread to resume it.

Dynamic Branding

The widget footer displays your configured branding. Logos switch automatically based on theme:

Dark themes or dark surface colors use the light (white) logo variant
Light themes use the dark logo variant
Falls back to default CloudStation branding if no custom logos are set

The branding toggle in widget settings controls whether the "Built on CloudStation" footer appears. You can disable it for a fully white-labeled experience.

Rate Limiting

Protect your project from abuse with configurable limits:

Daily message limit — maximum messages per day across all visitors
Per-visitor daily limit — maximum messages per visitor per day
Rate limit per minute — throttle burst traffic
Message length limit — cap the length of individual messages

Configure these in the Widget Designer section of project settings.

Allowed Domains

Restrict which websites can load your widget by specifying allowed domains. Use * to allow all domains, or list specific origins (one per line):

https://example.com
https://app.example.com

Multi-Channel Integration

Messages sent through the widget are tagged with a web source. If your project also receives messages from WhatsApp, Slack, Telegram, or the API, you can see all conversations in your Chat & Sessions view with source labels on each message.

What's Next?

Project Settings — Configure the widget designer
Chat & Sessions — View all conversations across channels
API Integration — Send messages programmatically