Widget — ChimerAI Docs

Overview

The Chat Widget is an embeddable chat bubble that you can drop into any website. It floats in the corner, opens a full conversation panel, and connects to your ChimerAI backend.

Quick Start

npx chimerai add chat-widget

This also generates middleware.ts (CORS headers) and adds CORS_ALLOWED_ORIGINS to .env. Run pnpm build after installation so the middleware becomes active.

Embed in Any Page

Option A — React component

import { ChatWidget } from '@/components/chat-widget/ChatWidget';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <ChatWidget
        title="Ask ChimerAI"
        placeholder="How can I help you today?"
        position="bottom-right"
      />
    </>
  );
}

Option B — Script tag (iFrame embed)

<script
  src="https://yourdomain.com/widget.js"
  data-api-url="https://yourdomain.com/api/chat"
  data-title="Ask us anything"
  defer
></script>

Props

Prop	Type	Default	Description
`title`	`string`	`"AI Assistant"`	Header text in the widget panel
`placeholder`	`string`	`"Type a message…"`	Input placeholder
`position`	`"bottom-right" \| "bottom-left"`	`"bottom-right"`	Widget placement
`systemPrompt`	`string`	—	Pre-configured system prompt
`modelId`	`string`	First active model	Override the AI model
`theme`	`"light" \| "dark" \| "auto"`	`"auto"`	Colour theme

Customise Appearance

<ChatWidget
  title="Support Chat"
  primaryColor="#6366f1" // indigo
  logoUrl="/logo.png"
/>

For full white-label theming (custom colours, logo, domain) see the Theming documentation.

API Route

The widget POSTs to /api/chat — the same route used by the full chat interface:

// POST /api/chat
// Body: { messages: Message[], modelId?: string, systemPrompt?: string }
// Response: text/event-stream (Vercel AI SDK data stream)

Architecture: Shadow DOM Web Component

The standalone widget.js bundle is a Web Component (<chimerai-chat>) using Shadow DOM — it does not leak CSS into your app and requires no React, Tailwind, or other dependencies.

<!-- Plain HTML / WordPress / any framework -->
<script src="https://your-chimerai.com/widget/chat.js" defer></script>
<chimerai-chat api-key="YOUR_API_KEY" title="Support Chat" position="bottom-right" theme="auto">
</chimerai-chat>

API key authentication

The widget authenticates via the x-api-key header on every streaming request to /api/v1/chat/stream:

# .env — generate via /api/v1/api-keys
CHIMERAI_WIDGET_API_KEY=ck_live_...

For production, use a backend proxy to keep the API key out of the browser:

// app/api/widget-proxy/route.ts
export async function POST(req: Request) {
  return fetch(`${process.env.AI_SERVICE_URL}/api/v1/chat/stream`, {
    method: 'POST',
    headers: {
      'x-api-key': process.env.CHIMERAI_WIDGET_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: req.body,
  });
}

Provider routing

The widget route calls providers directly where possible:

Provider	Type	Direct call?	Python AI service needed?
OpenAI	`openai`	✅ Yes	No
Anthropic	`anthropic`	✅ Yes	No
DeepSeek	`custom`	✅ Yes (OpenAI-compatible)	No
Groq	`groq`	❌ No	Yes
Ollama	`ollama`	❌ No	Yes
Google Gemini	`google`	❌ No	Yes

💡 DeepSeek works as a custom provider with baseUrl: https://api.deepseek.com/v1 — no Python service needed.

Programmatic control

const widget = document.querySelector('chimerai-chat');
widget.sendMessage('Hello!');
widget.clearHistory();
widget.setModel('gpt-4o');
widget.open();
widget.close();

Chat Widget — Integration Guide