> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Knowledge Base
> Upload documents and curate Q&A pairs to give your assistants context about your business
The knowledge base is the system that makes your assistants smart about your specific business. Instead of relying only on general AI knowledge, your assistants can read live data and search through your uploaded documents and curated Q\&A pairs to find accurate, relevant information before responding.
The Knowledge Base page is organized into two sections, each shown as a grid of **cards** — one card per source. Every card shows a quick summary (a connection or sync status, plus a count of what's in it), and **clicking a card opens that source's own management page** where you add and manage its content.
* **Realtime data** -- Connect live sources like **Shopify**, **WooCommerce**, and **Spreadsheets**. These are checked live every time someone chats (never indexed), so answers are always current.
* **Static knowledge** -- Content you add once, saved so your assistant can search it. Each source is its own card:
* **Files** -- Upload documents (PDF, Word, text, Markdown) that get indexed for semantic search
* **Websites** -- Crawl and index pages from your site
* **Text** -- Add freeform snippets directly
* **Q\&A Pairs** -- Create structured question-and-answer entries for precise, high-confidence responses
Each static card shows how many items it holds (e.g. "3 files") and a **sync status badge**, with an **Add** button to start adding content. Opening a card takes you to a focused page for just that source — for example, the **Files** card opens a page where you upload and manage only your files.
## Realtime Data Sources
Realtime data sources connect your assistant to systems that change constantly — your store catalog, orders, and fulfillment status. Unlike static knowledge, this data is **never indexed**; it's **checked live every time someone chats**, so customers always get the most current answer.
| Source | What it reads |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **Shopify** | Products, orders, carts, and customers from your Shopify store |
| **WooCommerce** | Products, orders, and customers from your WooCommerce store |
| **Spreadsheets** | A connected Google Sheet used as a live source of truth (e.g. order or fulfillment status) |
Each realtime source card shows a **connection-health badge** so you can see at a glance whether it's connected, and a **Test connection** button to verify it on demand.
Shopify, WooCommerce, and Spreadsheets used to live under **Channels**. They now live here, under **Knowledge Base → Realtime data**. Older links to the channel pages redirect here automatically. Availability depends on your plan.
## How It Works
IllumiChat uses Retrieval-Augmented Generation (RAG) to connect your documents to your assistants:
Open your assistant's **Knowledge Base**, then under **Static knowledge** open the **Files** card and upload your documents. Supported formats include PDF, Word, text, and Markdown.
IllumiChat extracts the text from your documents and splits it into smaller, meaningful chunks.
Each chunk is converted into a vector embedding -- a numerical representation that captures the meaning of the text. These are stored in a vector database for fast retrieval.
When someone sends a message to your assistant, IllumiChat searches the vector database for document chunks relevant to the question.
The assistant receives the relevant chunks as context alongside the user's question, then generates an accurate answer grounded in your actual documents.
## Supported File Types
| Format | Extension |
| -------------- | --------- |
| PDF | .pdf |
| Microsoft Word | .docx |
| Plain Text | .txt |
| Markdown | .md |
## Uploading Documents
Open the assistant you want to teach, then go to its **Knowledge Base**.
Under **Static knowledge**, click the **Files** card (or its **Add** button) to open the file management page.
Click the upload button and select files from your computer.
Each document shows a processing status so you know when it is ready. Once indexed, the assistant can search it automatically — there's no separate linking step.
## Processing Status
| Status | Meaning |
| -------------- | --------------------------------------------------------- |
| **Pending** | The document is queued for processing |
| **Processing** | Text extraction and indexing are in progress |
| **Completed** | The document is fully indexed and available to assistants |
| **Failed** | Something went wrong during processing (try re-uploading) |
Processing time depends on document size and complexity. Most documents complete within a few minutes.
## Keeping Static Knowledge Fresh
Static sources (files, websites, text, and Q\&A) are indexed once when you add them. To keep them current as your underlying content changes, each item shows a **sync status badge** and offers two ways to refresh it:
| Sync badge | Meaning |
| ----------- | ----------------------------------------- |
| **Synced** | The item is up to date and indexed |
| **Syncing** | A re-sync is currently running |
| **Failed** | The last sync didn't complete (try again) |
### Re-sync now
Use the **Re-sync now** button on any item to re-index it immediately — for example, after you've updated a webpage or replaced a document's contents.
### Auto-retrain
Set an **auto-retrain cadence** per item so IllumiChat re-syncs it on a schedule:
| Cadence | Behavior |
| ---------- | ------------------------------------------------------- |
| **Off** | The item is only re-synced when you trigger it manually |
| **Daily** | IllumiChat re-syncs the item about once a day |
| **Weekly** | IllumiChat re-syncs the item about once a week |
Auto-retrain is a paid feature. It's **off on the Free plan** and **available on Pro and Enterprise**. If you've just upgraded or a new release added the feature, your workspace admin may need to refresh plan features before the cadence selector appears.
## What Happens When You Delete an Assistant
When you delete an assistant, IllumiChat also cleans up the resources it owned so nothing is left behind:
* Its **knowledge base** is removed — uploaded files and indexed content are deleted, and the search index is reconciled automatically shortly afterward.
* If it was connected to **Shopify** or **WooCommerce**, IllumiChat removes the widget it installed on your store and unregisters the webhooks it created there.
Cleanup runs on a best-effort basis: if one step can't complete (for example, your store is temporarily unreachable), the assistant is still deleted and the rest of the cleanup proceeds. Messaging-channel connections (Messenger, Instagram, WhatsApp) are not yet detached automatically on deletion.
## Best Practices
Documents that cover one topic thoroughly work better than large documents covering many topics. This helps the retrieval system find the most relevant chunks.
Well-structured documents with clear headings, bullet points, and short paragraphs produce better search results.
Keep your knowledge base current by replacing outdated documents. Stale information leads to inaccurate answers.
After uploading documents, test your assistant with the kinds of questions your users will actually ask.
Group related documents into the same project. Keep product docs in one project, HR policies in another, and sales materials in a third.
## Q\&A Pairs
Q\&A pairs let you curate precise answers for frequently asked questions. When a user's question closely matches a stored Q\&A pair, the assistant returns the curated answer directly -- providing more concise, accurate responses than general document retrieval.
### How Q\&A Matching Works
IllumiChat uses a hybrid matching strategy for Q\&A pairs:
1. **Direct match** -- Your question text is embedded and compared semantically against stored Q\&A pairs. If the similarity score meets the confidence threshold, the paired answer is returned verbatim.
2. **RAG fallback** -- If there is no high-confidence direct match, Q\&A content participates in standard document retrieval alongside your uploaded files, so partial or indirect matches can still surface.
This means Q\&A pairs give you the best of both worlds: precise answers for known questions and fuzzy relevance for everything else.
Q\&A pairs share the same document quota as your uploaded files. Each Q\&A pair counts as one knowledge document.
### Adding Q\&A Pairs
Open the assistant you want to teach, then go to its **Knowledge Base**.
Under **Static knowledge**, click the **Q\&A Pairs** card. It sits alongside the Files, Websites, and Text cards.
Click **Add Q\&A** and fill in the **Question** and **Answer** fields.
Click **Save**. The Q\&A pair is automatically indexed and available to this assistant.
### Managing Q\&A Pairs
From the Q\&A Pairs card, you can:
* **Edit** an existing pair to update the question or answer
* **Delete** pairs that are no longer needed
* **View all pairs** in a list with the question and a preview of the answer
Start with Q\&A pairs for your top 10-20 most common support questions. These are the questions your team answers repeatedly -- giving your assistant curated answers for these dramatically improves response quality.
### When to Use Q\&A vs. Documents
| Use Case | Recommended Approach |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
| A specific question with a precise answer | **Q\&A pair** -- The assistant returns the exact answer you wrote |
| Detailed product documentation or guides | **Document upload** -- RAG retrieves relevant sections as needed |
| FAQ content you already have in a document | **Both** -- Upload the document and create Q\&A pairs for the most critical questions |
| Policies or procedures with nuance | **Document upload** -- Lets the assistant draw from the full context |
| Quick factual answers (hours, pricing, contact info) | **Q\&A pair** -- Ensures accuracy for simple lookups |
### Best Practices for Q\&A Pairs
Use natural, conversational phrasing. If your users ask "How do I reset my password?" rather than "Password reset procedure," write the question that way. The semantic matching works best when your stored question mirrors real user queries.
Write answers that fully address the question without unnecessary detail. If the answer requires a longer explanation, consider linking to a document or guide.
If a critical question can be asked in very different ways, consider adding separate Q\&A pairs for each variation to maximize match accuracy.
As your product or policies change, update your Q\&A pairs to stay current. Outdated answers erode user trust.
For the best support bot experience, combine Q\&A pairs for your most common questions with uploaded FAQs, help center articles, and troubleshooting guides. This gives your assistant precise answers for known questions and broad knowledge for everything else.