Widget Configuration

Complete reference for all configuration options. Every one of them is passed to RagChatsWidget.init() — the widget has no data-* attribute configuration.

Required Options

botIdstringrequired

Your bot's unique identifier. Find this in the Developer tab.

apiKeystringrequired

API key for widget authentication. Generate one in the Developer tab.

Connection Options

apiUrlstringdefault: the embedding page's own origin

Where RAG Chats lives. Always set this: the default resolves to YOUR site, not ours, so omitting it sends every request to your own domain. The generated snippet fills it in.

wsUrlstringdefault: derived from apiUrl

WebSocket URL for streaming. Defaults to the apiUrl host with a ws/wss scheme.

Appearance Options

positionstringdefault: bottom-right

Widget position. Options: "bottom-right", "bottom-left", "top-right", "top-left"

titlestringdefault: Chat

Title shown in the chat window header.

logoUrlstring

URL to your company/bot logo. Displayed in the header.

showBrandingbooleandefault: true

Show "Powered by RAG Chats" branding. Can be hidden on Pro+ plans.

Content Options

welcomeMessagestringdefault: Hello! How can I help you today?

Initial message shown when chat opens.

placeholderstringdefault: Type a message...

Placeholder text in the input field.

Behavior Options

autoExpandbooleandefault: false

Automatically open the chat window on page load.

persistSessionbooleandefault: true

Save conversation history in localStorage across page loads.

enableFileUploadbooleandefault: false

Allow users to upload files in chat (if enabled for your bot).

Trigger Options

Control how the widget button appears and behaves:

trigger.typestringdefault: button

Trigger type. Options: "button" (default), "auto-popup", "delay"

trigger.delaynumber

Delay in milliseconds before auto-opening (for "delay" type).

trigger.buttonTextstringdefault: Chat with us

Text shown on the chat button.

trigger.buttonIconstring

Custom icon for the button. Can be an emoji or image URL.

Theme Options

See the Theming guide for detailed customization options.

theme.primaryColorstringdefault: #6366f1

Primary color for buttons and accents.

theme.backgroundColorstringdefault: #ffffff

Chat window background color.

theme.textColorstringdefault: #1f2937

Main text color.

theme.fontFamilystringdefault: system-ui

Font family for all text.

theme.borderRadiusstringdefault: 16px

Border radius for the chat window.

Full Example

RagChatsWidget.init({
  500">class=500">class="text-green-500">"text-muted-foreground">// Required
  botId: 500">class="text-green-500">'bot_abc123',
  apiKey: 500">class="text-green-500">'pk_live_xxxxx',
  
  500">class=500">class="text-green-500">"text-muted-foreground">// Appearance
  position: 500">class="text-green-500">'bottom-right',
  title: 500">class="text-green-500">'Customer Support',
  logoUrl: 500">class="text-green-500">'https:500">class="text-muted-foreground500">class="text-green-500">">//example.com/logo.png',
  showBranding: 500">false,
  
  500">class=500">class="text-green-500">"text-muted-foreground">// Content
  welcomeMessage: 500">class="text-green-500">'Hi! I\'m here to help with any questions.',
  placeholder: 500">class="text-green-500">'Ask me anything...',
  
  500">class=500">class="text-green-500">"text-muted-foreground">// Behavior
  autoExpand: 500">false,
  persistSession: 500">true,
  enableFileUpload: 500">false,
  
  500">class=500">class="text-green-500">"text-muted-foreground">// Trigger
  trigger: {
    type: 500">class="text-green-500">'button',
    buttonText: 500">class="text-green-500">'Need help?',
    buttonIcon: 500">class="text-green-500">'💬'
  },
  
  500">class=500">class="text-green-500">"text-muted-foreground">// Theme
  theme: {
    primaryColor: 500">class="text-green-500">'#6366f1',
    backgroundColor: 500">class="text-green-500">'#ffffff',
    textColor: 500">class="text-green-500">'#1f2937',
    fontFamily: 500">class="text-green-500">'Inter, system-ui, sans-serif',
    borderRadius: 500">class="text-green-500">'16px',
    headerColor: 500">class="text-green-500">'#6366f1',
    userBubbleColor: 500">class="text-green-500">'#6366f1',
    assistantBubbleColor: 500">class="text-green-500">'#f3f4f6'
  },
  
  500">class=500">class="text-green-500">"text-muted-foreground">// Events
  onOpen: () => console.log(500">class="text-green-500">'Chat opened'),
  onClose: () => console.log(500">class="text-green-500">'Chat closed'),
  onMessage: (msg) => console.log(500">class="text-green-500">'Message:', msg),
  onError: (err) => console.error(500">class="text-green-500">'Error:', err)
});

Configuring the Script Tag Install

The script tag install takes exactly the same options as the NPM install: pass them to RagChatsWidget.init(). There are no data-* configuration attributes.

<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">'bot_abc123',
    apiKey: 500">class="text-green-500">'pk_live_xxxxx',
    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-left',
    title: 500">class="text-green-500">'Support',
    welcomeMessage: 500">class="text-green-500">'How can I help?',
    autoExpand: 500">false,
    theme: {
      primaryColor: 500">class="text-green-500">'#6366f1'
    }
  });
</script>

No data-* attributes

The widget never reads configuration off the script tag — it does not look at data-bot-id, data-api-key or any other attribute, and it does not start on its own. Everything, including nested objects like theme and trigger, is passed to init().

Updating Configuration

Update configuration at runtime:

500">class=500">class="text-green-500">"text-muted-foreground">// Update single option
RagChatsWidget.updateConfig({
  title: 500">class="text-green-500">'New Title'
});

500">class=500">class="text-green-500">"text-muted-foreground">// Update theme
RagChatsWidget.updateConfig({
  theme: {
    primaryColor: 500">class="text-green-500">'#10b981'
  }
});