RAG ChatsRAG Chats

Widget Installation

Choose the installation method that works best for your project. All methods provide the same functionality.

Copy the snippet from your dashboard

The examples below are generated by the same code that fills in the snippet on your bot's Developer → Widget tab, so they always match your deployment. Copy from there to get your real Bot ID and API Key filled in for you.

Method 1: Script Tag (Simplest)

Add these two script tags before the closing </body> tag. The first one loads the widget and defines the global RagChatsWidget; the second one starts it. Both are required — loading the bundle on its own renders nothing.

<!-- RAG Chats Widget -->
<script src=500">class="text-green-500">"https:500">class="text-muted-foreground500">class="text-green-500">">//ragchats.ai/widget/widget.min.js"></script>
<script>
  RagChatsWidget.init({
    botId: 500">class="text-green-500">'YOUR_BOT_ID',
    apiKey: 500">class="text-green-500">'YOUR_API_KEY',
    apiUrl: 500">class="text-green-500">'https:500">class="text-muted-foreground500">class="text-green-500">">//ragchats.ai',
    wsUrl: 500">class="text-green-500">'wss:500">class="text-muted-foreground500">class="text-green-500">">//ragchats.ai',
    position: 500">class="text-green-500">'bottom-right',
    title: 500">class="text-green-500">'Chat with us',
    welcomeMessage: 500">class="text-green-500">'Hi! How can I help you today?',
    placeholder: 500">class="text-green-500">'Type your message...',
    showBranding: 500">true,
    autoExpand: 500">false,
    theme: {
      primaryColor: 500">class="text-green-500">'#6366f1',
      headerColor: 500">class="text-green-500">'#4f46e5'
    }
  });
</script>

There is no data-attribute auto-start

The widget does not read data-bot-id or any other data-* attribute off the script tag, and it does not start itself. You must call RagChatsWidget.init()explicitly, exactly as shown above. Configure it by passing options to that call — see Configuration for the full list.

Why apiUrl and wsUrl are in the snippet

The snippet runs on your website, so the widget cannot infer where RAG Chats lives — without these two options it would try to reach your own domain and every request would fail. They are filled in for you; copy them as-is.

Deferring the load

If you want to load the bundle asynchronously, add async to the first tag and move the init() call into its onload handler, so it cannot run before RagChatsWidget exists:

<script
  src=500">class="text-green-500">"https:500">class="text-muted-foreground500">class="text-green-500">">//ragchats.ai/widget/widget.min.js"
  500">async
  onload=500">class="text-green-500">"RagChatsWidget.init({ botId: 'YOUR_BOT_ID500">class="text-green-500">', apiKey: 'YOUR_API_KEY500">class="text-green-500">' })"
></script>

Method 2: NPM Package

For JavaScript/TypeScript projects with a build system:

-purple-500">npm install @rag-chats/widget

Then initialize the widget in your code:

500">import RagChatsWidget 500">from 500">class="text-green-500">'@rag-chats/widget';

500">class=500">class="text-green-500">"text-muted-foreground">// Initialize in your app
RagChatsWidget.init({
  botId: 500">class="text-green-500">'YOUR_BOT_ID',
  apiKey: 500">class="text-green-500">'YOUR_API_KEY',
  apiUrl: 500">class="text-green-500">'https:500">class="text-muted-foreground500">class="text-green-500">">//ragchats.ai',
  wsUrl: 500">class="text-green-500">'wss:500">class="text-muted-foreground500">class="text-green-500">">//ragchats.ai',
  position: 500">class="text-green-500">'bottom-right',
  title: 500">class="text-green-500">'Chat with us',
  welcomeMessage: 500">class="text-green-500">'Hi! How can I help you today?',
  theme: {
    primaryColor: 500">class="text-green-500">'#6366f1',
    headerColor: 500">class="text-green-500">'#4f46e5'
  }
});

500">class=500">class="text-green-500">"text-muted-foreground">// Cleanup on unmount
500">class=500">class="text-green-500">"text-muted-foreground">// RagChatsWidget.destroy();

TypeScript Support

The package includes TypeScript definitions. You get full type safety and autocomplete:

500">import RagChatsWidget, { WidgetConfig } 500">from 500">class="text-green-500">'@rag-chats/widget';

500">const config: WidgetConfig = {
  botId: 500">class="text-green-500">'YOUR_BOT_ID',
  apiKey: 500">class="text-green-500">'YOUR_API_KEY',
  theme: {
    primaryColor: 500">class="text-green-500">'#6366f1',
    backgroundColor: 500">class="text-green-500">'#ffffff',
  },
  onMessage: (message) => {
    console.log(500">class="text-green-500">'New message:', message.content);
  }
};

RagChatsWidget.init(config);

iframe Embed

Not currently available

There is no iframe embed today. RAG Chats serves every page with frame-ancestors 'none', so an iframe embed would be blocked by your visitors' browsers rather than render. Use the script tag or the NPM package — both give you full programmatic control, which the iframe method never did.

The widget already isolates its own styles with a Shadow DOM, so you do not need an iframe to keep your CSS and the widget's CSS apart.

Verifying Installation

After installation, verify the widget is working:

  1. Refresh your page
  2. Look for the chat button (default: bottom-right corner)
  3. Click to open and send a test message
  4. Check browser console for any errors

Common Issues

Widget not appearing?

  • Confirm you copied both script tags — the bundle alone does nothing without the init() call
  • Check that Bot ID and API Key are correct
  • Verify your domain is whitelisted in bot settings
  • Check browser console for errors
  • Ensure the script is loading (Network tab in DevTools)

CORS errors, or the connection never opens?

  • Add your domain to the allowed domains list in bot settings
  • Your site's origin is checked against that list on both the API request and the WebSocket handshake, so a missing entry looks like a connection that closes immediately
  • localhost is automatically allowed for development

Style conflicts?

  • The widget uses Shadow DOM to isolate its styles
  • If you see issues, check for global CSS resets that might affect the widget container

Content Security Policy

If your site uses CSP, add these directives:

script-src 500">class="text-green-500">'self' https:500">class=500">class="text-green-500">"text-muted-foreground">//ragchats.ai;
connect-src 500">class="text-green-500">'self' https:500">class=500">class="text-green-500">"text-muted-foreground">//ragchats.ai wss://ragchats.ai;

Next Steps