Skip to main content

​
Welcome to Open Chat Widget

A complete, production-ready AI chat solution that you can self-host and customize. Built with modern technologies and designed for easy integration into any website or application.

Quickstart

Get your chat widget running locally in under 5 minutes

Architecture

Understand how the system components work together

Embedding the Widget

Add the chat widget to your website with a simple script tag

API Reference

Integrate headless chat endpoints into custom frontends

​
What is Open Chat Widget?

Open Chat Widget is a full-stack, open-source AI chatbot platform that provides everything you need to add intelligent conversational support to your website:
  • Embeddable Widget - Drop-in JavaScript bundle with customizable styling
  • Headless API - REST endpoints for building custom chat interfaces
  • Real-time Streaming - Token-by-token responses for instant user feedback
  • Admin Dashboard - Next.js dashboard to view and manage conversations
  • Self-hosted - Full control over your data with Convex backend
  • Production-ready - Built-in security, rate limiting, and Docker support

​
Key Features

​
Easy Integration

Embed the chat widget with a single script tag: 
<script
  src="http://localhost:4000/widget/chat-widget.js"
  data-api-url="http://localhost:4000/chat"
  data-api-key="your-api-key"
  data-title="Support"
  data-welcome-message="Hey! How can I help?"
  data-position="right"
  data-accent-color="#0ea5e9"
  defer
></script>

​
Customizable Appearance

Control the widget’s look and feel through data attributes:
  • Custom title and welcome message
  • Configurable accent colors
  • Left or right positioning
  • Custom input placeholder text
  • Responsive design that works on mobile

​
Headless API Option

Prefer to build your own UI? Use the REST API directly: 
const response = await fetch("https://your-backend.com/v1/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "your-widget-api-key"
  },
  body: JSON.stringify({
    sessionId: "user-session-123",
    message: "Hello, I need help"
  })
});

const data = await response.json();
// { conversationId: "...", message: "..." }

​
Conversation Management

The admin dashboard provides:
  • List all conversations sorted by recent activity
  • View full conversation threads with timestamps
  • Session-based tracking for returning users
  • Persistent storage with Convex database

​
Enterprise-Ready Security

Built with security best practices from day one
  • API key authentication (separate keys for chat and admin)
  • Rate limiting by IP address
  • CORS configuration with origin allowlist
  • Timing-safe credential comparison
  • Security headers (X-Frame-Options, CSP, HSTS)
  • Password-protected admin dashboard

​
Tech Stack

Built with modern, proven technologies:
ComponentTechnology
WidgetVanilla TypeScript, esbuild
Backend APINode.js, Express
DatabaseConvex (real-time, serverless)
DashboardNext.js 15, React Server Components
AI ProviderOpenAI GPT-4
DeploymentDocker, Docker Compose

​
Use Cases

Customer SupportAnswer common questions 24/7 with AI-powered responses

Educational SitesProvide instant help to students learning on your platform

E-commerceGuide shoppers through product selection and checkout

DocumentationHelp developers find answers in your technical docs

Booking & ReservationsAssist users with scheduling and appointments

Internal ToolsAdd conversational interfaces to company dashboards

​
Next Steps

1

Run locally

Follow the Quickstart guide to get the widget running on your machine
2

Understand the architecture

Read the Architecture overview to learn how components interact
3

Embed the widget

Add the widget to your website and customize its appearance
4

Deploy to production

Host on your preferred platform (Railway, Render, Vercel, or Docker)
Open Source & MIT LicensedFree to use, modify, and deploy. Contribute on GitHub or adapt to your needs.

Build docs developers (and LLMs) love

Get started for freeTalk to us