Chat Interface¶

The RAG Chatbot includes an embeddable chat widget that can be added to any website. This guide covers using and customizing the chat interface.

Overview¶

The chat widget provides:

Real-time question and answer interface
Document upload capability
Media URL import (YouTube, etc.)
Conversation history
Mobile-responsive design

Header Controls¶

The chat window header contains three buttons:

Button	Icon	Function
New Chat	+	Start a fresh conversation
Upload	↑	Open document/media upload modal
Close	×	Close the chat window

Starting a New Conversation¶

Click the + button in the header to start a new conversation. This will:

Prompt for confirmation
Clear local chat history
Generate a new session ID
Display a welcome message

When to Start New

Start a new conversation when:

Switching to a different topic
The conversation becomes too long
You see a "conversation limit reached" message

Sending Messages¶

Type your question in the input field
Press Enter or click the send button
Wait for the AI response (indicated by typing animation)

The AI will search your uploaded documents and provide answers based on relevant content.

Understanding Responses¶

Responses may include:

Direct answers - Information found in your documents
Source citations - References to specific documents
"No information" messages - When relevant content isn't found

Basic Integration¶

Add the widget to any HTML page:

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <!-- Your page content -->

    <!-- Chat Widget -->
    <script src="https://your-domain.com/chatbot/public/chat-widget.js"></script>
</body>
</html>

Configuration Options¶

Customize the widget before loading:

<script>
    // API endpoint (required if different from default)
    window.RAG_CHATBOT_API = '/chatbot/public/chat';

    // Upload endpoint
    window.RAG_CHATBOT_UPLOAD_API = '/chatbot/public/upload.php';

    // Widget position: 'bottom-right', 'bottom-left', 'top-right', 'top-left'
    window.RAG_CHATBOT_POSITION = 'bottom-right';

    // Primary color (CSS color value)
    window.RAG_CHATBOT_COLOR = '#0d6efd';

    // Chat window title
    window.RAG_CHATBOT_TITLE = 'Help';
</script>
<script src="/chatbot/public/chat-widget.js"></script>

Programmatic Control¶

Control the widget via JavaScript:

// Open the chat window
RAGChatbot.open();

// Close the chat window
RAGChatbot.close();

// Open the upload modal
RAGChatbot.openUpload();

// Close the upload modal
RAGChatbot.closeUpload();

// Clear history and start fresh
RAGChatbot.clearHistory();

Upload Features¶

File Upload Tab¶

Click the upload button (↑) to open the upload modal.

Supported file formats:

Category	Extensions
Documents	PDF, DOCX, PPTX, XLSX
Text	TXT, MD, HTML, CSV, JSON
Images	PNG, JPG, GIF, WebP, TIFF, BMP
Audio	WAV, MP3, M4A, OGG, FLAC
Subtitles	SRT, VTT

To upload files:

Click the upload button in the header
Select the "Upload File" tab
Drag and drop files, or click to browse
Click "Upload & Import"

Multiple Files

You can select and upload multiple files at once. Each file is processed individually.

Media URL Tab¶

Import content from video and audio platforms:

Supported platforms:

YouTube (videos and playlists)
SoundCloud
TED Talks
Twitch
Twitter/X
TikTok
And 1000+ more via yt-dlp

To import from a URL:

Click the upload button in the header
Select the "Media URL" tab
Paste the video/audio URL
Click "Upload & Import"

The system will:

Download subtitles (if available)
Transcribe audio (if no subtitles)
Import the transcript into the knowledge base

Playlists¶

When you paste a YouTube playlist URL:

All videos in the playlist are processed
Each video becomes a separate document
Failed imports show retry buttons
Progress is displayed during processing

Conversation Memory¶

How It Works¶

The chatbot maintains conversation context:

Recent messages (last 6) are sent with each request
Older messages are automatically summarized
Summaries preserve key topics and decisions

This allows for long conversations without losing context.

Example¶

Imagine a conversation about a company's financial reports:

Message #	You Ask	What the AI Sees
1-6	Questions about Q1 revenue, expenses, profit margins...	Full message history
7-10	More questions about Q2 projections...	Summary: "User analyzed Q1 financials: revenue $2.1M, expenses discussed, interested in profit margins" + Messages 5-10
11+	"How does that compare to Q1?"	The AI still knows you discussed Q1 data, even though those original messages were summarized

Without conversation memory, message 11 would fail—the AI wouldn't know what "Q1" refers to. With summarization, key context is preserved while keeping requests efficient.

Limits¶

Limit	Value
Maximum total messages	500 per session
Message length	10,000 characters
Summary length	8,000 characters

When the conversation limit is reached, you'll see a message prompting you to start a new conversation.

Mobile Usage¶

The chat widget is fully responsive:

On mobile devices, the chat opens fullscreen
Touch-friendly interface
Swipe gestures supported
File upload works with mobile file pickers

Styling Customization¶

CSS Variables¶

Override default styles with CSS:

#rag-chat-widget {
    --bs-primary: #your-brand-color;
    --bs-border-radius: 8px;
    --bs-border-radius-lg: 12px;
}

Custom Positioning¶

#rag-chat-widget {
    /* Override position */
    right: 2rem !important;
    bottom: 2rem !important;
}

#rag-chat-widget .rag-chat-window {
    /* Custom window size */
    width: 400px;
    height: 600px;
}

Best Practices¶

Asking Effective Questions¶

For best results:

Be specific - "What does the Q3 report say about revenue?" vs "Tell me about revenue"
Provide context - "In the employee handbook, what is the vacation policy?"
Ask follow-ups - The AI remembers your conversation context

Managing Documents¶

Use descriptive filenames - They help identify sources in responses
Upload related documents together - Improves cross-referencing
Keep documents current - Remove outdated content

Performance Tips¶

Large files (>50MB) may take longer to process
YouTube playlists process videos sequentially
Audio transcription is slower than subtitle extraction

Troubleshooting¶

Chat Not Loading¶

Check browser console for JavaScript errors
Verify the script URL is correct
Ensure CORS is configured if hosting on a different domain

Upload Failures¶

Check file size limits (default 100MB)
Verify file format is supported
Ensure the Docling service is running

Slow Responses¶

Large documents take longer to search
First request may be slower (model loading)
Check network connectivity

"No Information" Responses¶

This occurs when:

No relevant documents have been uploaded
The question doesn't match document content
Search threshold is too high

Try:

Rephrasing your question
Uploading more relevant documents
Using the debug endpoint to diagnose