Widget Configuration

Complete reference for all configuration options. Pass these to RagChatsWidget.init() or use data attributes.

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: https://api.ragchats.ai

API base URL. Only change for self-hosted deployments.

wsUrlstringdefault: wss://api.ragchats.ai

WebSocket URL for streaming. Derived from apiUrl by default.

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)
});

Data Attributes

When using the script tag, you can set options via data attributes. Convert camelCase to kebab-case:

<script
  src=500">class="text-green-500">"https:500">class="text-muted-foreground500">class="text-green-500">">//widget.ragchats.ai/embed.js"
  data-bot-id=500">class="text-green-500">"bot_abc123"
  data-api-key=500">class="text-green-500">"pk_live_xxxxx"
  data-position=500">class="text-green-500">"bottom-left"
  data-title=500">class="text-green-500">"Support"
  data-welcome-message=500">class="text-green-500">"How can I help?"
  data-primary-color=500">class="text-green-500">"#6366f1"
  data-auto-expand=500">class="text-green-500">"500">false"
  500">async
></script>

Nested Options

Data attributes don't support nested objects like theme or trigger. For full customization, use the NPM package and 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'
  }
});