Web Widget
Embed a fully functional AI chat widget on your website in minutes. The web widget brings your agent directly to your users with customizable themes, responsive design, and real-time streaming responses — no iframe or third-party platform required.
Easy Embed
Single script tag with a few lines of initialization code
Fully Customizable
Colors, fonts, positions, and behavior through a rich configuration API
Responsive by Default
Works seamlessly on desktop, tablet, and mobile viewports
Overview
The web widget is a lightweight JavaScript library that renders a chat interface as an overlay on your website. It connects directly to your 8bit-ai agent via WebSocket for real-time communication. The widget handles connection management, session persistence, message history, and automatic reconnection.
How It Works
- Visitor clicks the widget button (or it opens automatically)
- Widget establishes a WebSocket connection to the agent
- Visitor types a message and sends it
- Agent processes the message via its LLM and knowledge base
- Response streams back through the WebSocket in real-time
- Conversation persists in browser localStorage for continuity
Key Features
- Real-time streaming with typing indicators
- Markdown rendering for rich responses
- Automatic session recovery on page refresh
- Configurable greeting messages
- Optional user authentication via JWT
- Custom CSS variable overrides
Embedding
Add the widget to any HTML page by including the script and initializing it with your agent ID. The widget loads asynchronously and does not block page rendering.
Add the Script
Include the widget script in your HTML, preferably before the closing</body> tag.
Initialize the Widget
Call the initialization function with your agent ID and optional configuration.
Finding Your Agent ID
ag_.Verify Deployment
Open your website in a browser. A chat bubble should appear in the configured position. Click it to open the widget and start a conversation.
What to Check
- Widget button renders in the correct position
- Clicking the button opens the chat panel
- Sending a message produces a response from your agent
- Widget is fully responsive on mobile viewports
Content Security Policy
connect-src wss://*.8bit-ai.com,script-src https://cdn.8bit-ai.com.Customization
The widget exposes a comprehensive configuration API. Pass options to theinit() method or update them at runtime.
Configuration Options
Runtime Updates
Update widget configuration after initialization using the global instance:
Theming
The widget supports light, dark, and auto themes. For deeper customization, use CSS custom properties to override individual design tokens.
Theme Presets
Light
theme: 'light'White background, dark text, primary accents
Dark
theme: 'dark'Dark background, light text, primary accents
Auto
theme: 'auto'Follows the user's system preference via prefers-color-scheme
CSS Custom Properties
Override these variables on your site to customize widget appearance:
CSS Variable Precedence
theme option. Use them for fine-grained brand alignment without changing the base theme.Events & Hooks
Subscribe to widget lifecycle events to integrate with your analytics, custom logging, or third-party tools.
Event Reference
| Event | Payload | Description |
|---|---|---|
| widget:open | Widget panel was opened | |
| widget:close | Widget panel was closed | |
| message:send | { text, timestamp } | User sent a message |
| message:receive | { text, timestamp } | Agent delivered a response |
| session:start | { sessionId } | A new conversation session began |
| session:end | { sessionId, duration } | Session expired or was closed |
| error | { code, message } | An error occurred (connection, auth, etc.) |
Subscribing to Events
Authentication Events
userToken, the widget emitsauth:success andauth:error events with the decoded token payload or error details.