Stella AI Chatbot installation and user guide covering FAQ automation, lead capture, AI conversations, RAG, human handoff, and Pro analytics for websites.

This guide covers both Free and Pro editions in one place. Where a feature is Pro-only, it is marked (Pro).

1. Installation

1.1 Requirements

Node.js 18+ - Required runtime to run the chatbot backend server.
npm - Required to install project dependencies.
Modern browser - Required to access admin panel and test widget behavior.
PostgreSQL 13+ (Pro optional) - Required only if you choose PostgreSQL storage mode.
pgvector (Pro optional) - Required for PostgreSQL vector similarity search in RAG mode.
Ollama (Pro optional) - Required only if you want local embedding generation with zero API cost.

1.2 Download and Prepare

Extract package - Unzip either stella-ai-chatbot-free or stella-ai-chatbot-pro.
Open folder in terminal - Run all install/start commands from this directory.
Install dependencies - Downloads all required backend libraries.

npm install

1.3 Configure Environment

Create .env - Copy .env.example to .env.
Set required variables:
- NODE_ENV - Defines runtime mode (development or production).
- APP_SECRET - Used to sign/verify secure tokens and sessions.
- ADMIN_USER - Admin login username.
- ADMIN_PASS - Admin login password.
- INSTALL_TOKEN - Protects installer from unauthorized access.
- CORS_ORIGINS / ALLOWED_ORIGINS - Controls which origins can call APIs.
- DATA_ENCRYPTION_KEY - Used for encryption of sensitive data (if supported in your edition).
Optional variables:
- PORT - Server port (platform can override dynamically).
- TRUST_PROXY=true - Enable correct IP detection behind reverse proxy/CDN.

1.4 Start Application

npm start

/install - First-time setup wizard.
/admin - Admin login and dashboard.

1.5 Installer Steps

Open installer - /install Initializes chatbot system.
Enter install token - Confirms authorized installation.
Select storage mode:
- Free: JSON storage.
- Pro: JSON or PostgreSQL.
Complete install - Creates required defaults/settings.
install.lock generated - Prevents accidental reinstallation and it is present in the data folder.

1.6 Embed Widget on Any Website

Open Embed Code section - Generates script for frontend integration.
Copy script - Includes widget loader and API base URL.
Paste before </body> - Ensures widget loads after page content.
Refresh site - Verifies chatbot appears and works.

1.7 Production Checklist

Enable HTTPS - Protects traffic and credentials.
Use strong secrets - Prevents token/session compromise.
Restrict domains - Prevents widget/API misuse on unauthorized sites.
Protect installer - Blocks public reinstall attacks.
Enable CSRF/security controls - Protects admin write actions.
Set retention policy - Keeps logs manageable and compliant.

2. User Guide (Step-by-Step)

2.1 Admin Login

Open /admin - Access admin entry page.
Sign in - Uses credentials from .env.
Navigate menu - Overview, Settings, FAQs, Logs.

2.2 Overview Page

Usage stats - Shows chatbot activity summary.
Matched vs unmatched - Shows answer quality trend.
Top matched keywords - Identifies what users ask successfully.
Top unmatched questions - Shows FAQ/AI content gaps to improve.

2.3 Settings Page

A. Core Identity

Chatbot Name - Display title shown in the chat header.
Avatar Upload - Brand image shown in widget launcher and chat.
Avatar Shape - Controls whether avatar appears round or square.
Show Live Preview - Toggles real-time preview in admin settings page.

B. Messaging & Engagement

Welcome Message - Message shown when a user opens the chatbox.
No Match Message - Fallback response when no answer is found.
Fuzzy Match - Matches similar keywords/questions even if not exact.
Fuzzy Threshold - Controls strictness of fuzzy matching.
Lead Capture - Collects visitor name/email before or during chat.
Lead Capture Prompt - Message shown when asking for user details.

C. Widget Appearance

Widget Position - Places launcher on left or right side.
Widget Size - Controls launcher diameter/visual footprint.
Brand/Theme Colors - Matches widget with your site branding.
Avatar Size - Controls bot avatar size inside chat UI.
Animation - Adds attention effects like pulse/shake/float.
Chatbox Width/Height - Controls conversation panel dimensions.

D. System & Performance

Items Per Page - Pagination size for admin tables.
Log Retention Days - Days to keep logs before cleanup.
Auto Cleanup - Automatically deletes old data by retention rule.
Enforce HTTPS - Blocks insecure non-HTTPS requests (non-localhost).
Enforce Admin CSRF - Requires CSRF token for admin write operations.

E. Categories

Add Category - Creates new grouping for FAQ/chat flows.
Recommended Categories - Up to 3 categories shown first in widget.
Delete Category - Removes unused category (or merge/reassign logic applies).

F. Embed Code

API Base URL - Defines backend URL used by widget script.
Allowed Widget Domains - Restricts where widget can run.
Widget Domain Policy - restricted enforces allowed domain list.
Regenerate / Copy Code - Refreshes and copies embed script.

2.4 Pro Features in Settings (Pro)

A. Human Handoff (Pro)

Enable Handoff - Activates escalation to human support.
Escalate After Unmatched - Number of failed matches before handoff.
Handoff Message - Message shown when escalation triggers.
Support URL - Link users click to contact human support.
Business Hours - Optional time window to trigger handoff behavior.

B. AI Powered Responses (Pro)

AI Provider - Selects backend LLM service.
API Key - Auth key for selected provider.
Load Models - Fetches available models for that provider/key.
AI Model - Model used for response generation.
Test Connection - Validates key/model/provider setup.
Max Tokens - Maximum response output length from AI model.
System Instructions - Defines bot behavior/tone/rules.
AI Disclaimer - Optional caution text shown under AI answers.

C. Vector Retrieval (RAG) (Pro)

Enable RAG - Allows retrieval from indexed website content.
Use PostgreSQL pgvector - Enables scalable vector storage/search.
Embedding Provider - Service used to convert text to vectors.
Embedding API Key - Authentication for embedding provider.
Fetch Models - Loads available embedding models.
Embedding Model - Model used for indexing and query embeddings.
Test Embedding Connection - Verifies embedding endpoint works.
Crawl Root URL / Sitemap - Defines crawl starting points.
Max Pages / Max Depth - Controls crawl size and recursion depth.
Chunk Size / Overlap - Controls text segmentation for retrieval quality.
Include / Exclude Patterns - Fine control over crawled URLs.
Resume Mode - Skips already indexed URLs during recrawl.
Crawl Website Content - Starts indexing job.
RAG Ranking Mode - Controls ranking strategy (Balanced / Exact Product First).

2.5 FAQs Page

Add FAQ - Manual Q&A creation with unique keyword.
Edit/Delete FAQ - Maintain and correct existing responses.
Import File - Bulk upload FAQs from TXT/CSV/CSB/DOCX.
Delimiter Option - Parses custom file formats (:, ,, |, etc).
Duplicate Keyword Handling - Skip or suffix duplicates during import.
Category Handling - Create missing categories or use fallback category.
Import Summary - Shows added/rejected/duplicate counts.

2.6 Logs Page

Session Filters - Search by session key, name, or email.
Show Chat - Opens chat history for selected session only.
Leads Table - Displays captured visitor contact details.
Pagination - Navigate large datasets efficiently from top/bottom controls.

2.7 Frontend Behavior

Widget Open - User opens launcher and enters chat.
Welcome/Categories - Intro and recommendations appear (if enabled).
User Query Handling:
- Free: FAQ + fuzzy match flow.
- Pro: FAQ + AI + RAG + handoff rules.
Lead Collection - Name/email prompt appears when enabled.
Logging - Session/messages/leads saved for analytics.

2.8 Troubleshooting

Widget not visible - Validate embed code, domain policy, and browser console.
Short AI answers - Try another model/provider, raise max tokens, test provider response metadata.
RAG not answering - Confirm crawl success, embedding config, and ranking mode.
Install blocked - Verify install token and lock/maintenance behavior.

2.9 Recommended Rollout Path

Start with FAQ + categories - Build reliable baseline answers.
Enable fuzzy match - Improve question tolerance.
Enable lead capture - Start collecting qualified contacts.
(Pro) Enable AI - Handle broader natural-language queries.
(Pro) Enable RAG - Ground answers in your own site content.
(Pro) Enable handoff - Escalate complex user needs to humans.
Finalize security + deploy - Lock policy and go production.

Stella AI Chatbot: Installation and User Guide for Websites