Den här guiden täcker både Free- och Pro-versionerna på ett och samma ställe. Där en funktion endast finns i Pro är den markerad med (Pro).

1. Installation

1.1 Krav

Node.js 18+ - Krävs för att köra chatbotens backend-server.
npm - Krävs för att installera projektets beroenden.
Modern webbläsare - Krävs för att öppna adminpanelen och testa widgetens beteende.
PostgreSQL 13+ (valfritt i Pro) - Krävs endast om du väljer PostgreSQL-lagringsläge.
pgvector (valfritt i Pro) - Krävs för PostgreSQL-baserad vektorlikhetssökning i RAG-läge.
Ollama (valfritt i Pro) - Krävs endast om du vill generera lokala embeddings utan API-kostnad.

1.2 Ladda ner och förbered

Packa upp paketet - Packa upp antingen stella-ai-chatbot-free eller stella-ai-chatbot-pro.
Öppna mappen i terminalen - Kör alla installations-/startkommandon från den här katalogen.
Installera beroenden - Laddar ner alla nödvändiga backend-bibliotek.

npm install

1.3 Konfigurera miljön

Skapa .env - Kopiera .env.example till .env.
Ange obligatoriska variabler:
- NODE_ENV - Definierar körläge (development eller production).
- APP_SECRET - Används för att signera/verifiera säkra tokens och sessioner.
- ADMIN_USER - Användarnamn för admininloggning.
- ADMIN_PASS - Lösenord för admininloggning.
- INSTALL_TOKEN - Skyddar installationen mot obehörig åtkomst.
- CORS_ORIGINS / ALLOWED_ORIGINS - Styr vilka origins som får anropa API:er.
- DATA_ENCRYPTION_KEY - Används för kryptering av känslig data (om stöds i din version).
Valfria variabler:
- PORT - Serverport (plattformen kan skriva över dynamiskt).
- TRUST_PROXY=true - Aktiverar korrekt IP-detektering bakom reverse proxy/CDN.

1.4 Starta applikationen

npm start

/install - Installationsguide för första gången.
/admin - Admininloggning och dashboard.

1.5 Installationssteg

Öppna installationen - /install initierar chatbotsystemet.
Ange installationstoken - Bekräftar behörig installation.
Välj lagringsläge:
- Free: JSON-lagring.
- Pro: JSON eller PostgreSQL.
Slutför installationen - Skapar nödvändiga standardvärden/inställningar.
install.lock skapas - Förhindrar oavsiktlig ominstallation och finns i data-mappen.

1.6 Bädda in widget på valfri webbplats

Öppna avsnittet Embed Code - Genererar script för frontend-integration.
Kopiera scriptet - Innehåller widget-laddare och API-bas-URL.
Klistra in före </body> - Säkerställer att widgeten laddas efter sidinnehållet.
Uppdatera webbplatsen - Verifierar att chatboten visas och fungerar.

1.7 Checklista för produktion

Aktivera HTTPS - Skyddar trafik och inloggningsuppgifter.
Använd starka hemligheter - Förhindrar att token/session komprometteras.
Begränsa domäner - Förhindrar missbruk av widget/API på obehöriga webbplatser.
Skydda installationen - Blockerar offentliga återinstallationsattacker.
Aktivera CSRF-/säkerhetskontroller - Skyddar admin-ändringar.
Ange retention-policy - Håller loggar hanterbara och kompatibla.

2. Användarguide (Steg för steg)

2.1 Admininloggning

Öppna /admin - Öppnar admins startsida.
Logga in - Använder inloggningsuppgifter från .env.
Navigera i menyn - Overview, Settings, FAQs, Logs.

2.2 Overview-sidan

Användningsstatistik - Visar sammanfattning av chatbot-aktivitet.
Matched vs unmatched - Visar trend för svarskvalitet.
Topp matchade nyckelord - Identifierar vad användare frågar om och får svar på.
Topp omatchade frågor - Visar luckor i FAQ/AI-innehåll som bör förbättras.

2.3 Settings-sidan

A. Core Identity

Chatbot Name - Rubrik som visas i chatthuvudet.
Avatar Upload - Varumärkesbild i widget-knapp och chatt.
Avatar Shape - Styr om avataren visas rund eller fyrkantig.
Show Live Preview - Slår av/på realtidsförhandsvisning i admin.

B. Messaging & Engagement

Welcome Message - Meddelande som visas när användaren öppnar chatten.
No Match Message - Reservsvar när inget matchande svar hittas.
Fuzzy Match - Matchar liknande nyckelord/frågor även utan exakt träff.
Fuzzy Threshold - Styr hur strikt fuzzy matchning ska vara.
Lead Capture - Samlar in namn/e-post före eller under chatten.
Lead Capture Prompt - Meddelande som visas när användardata efterfrågas.

C. Widget Appearance

Widget Position - Placerar widget-knappen till vänster eller höger.
Widget Size - Styr launcher-knappens storlek.
Brand/Theme Colors - Matchar widgetens färger med webbplatsens varumärke.
Avatar Size - Styr avatarstorlek i chattgränssnittet.
Animation - Lägger till effekter som pulse/shake/float.
Chatbox Width/Height - Styr dimensionerna på chattpanelen.

D. System & Performance

Items Per Page - Antal poster per sida i admin-tabeller.
Log Retention Days - Hur länge loggar sparas innan rensning.
Auto Cleanup - Tar automatiskt bort gammal data enligt retention-regel.
Enforce HTTPS - Blockerar osäkra icke-HTTPS-anrop (ej localhost).
Enforce Admin CSRF - Kräver CSRF-token för admin-ändringar.

E. Categories

Add Category - Skapar ny gruppering för FAQ/chattflöden.
Recommended Categories - Upp till 3 kategorier visas först i widgeten.
Delete Category - Tar bort oanvänd kategori (eller merge/omfördelning används).

F. Embed Code

API Base URL - Definierar backend-URL som widgetscriptet använder.
Allowed Widget Domains - Begränsar var widgeten får köras.
Widget Domain Policy - restricted kräver lista över tillåtna domäner.
Regenerate / Copy Code - Uppdaterar och kopierar embed-script.

2.4 Pro-funktioner i Settings (Pro)

A. Human Handoff (Pro)

Enable Handoff - Aktiverar eskalering till mänsklig support.
Escalate After Unmatched - Antal misslyckade matcher innan handoff.
Handoff Message - Meddelande som visas när eskalering triggas.
Support URL - Länk användaren klickar för mänsklig support.
Business Hours - Valfritt tidsfönster för handoff-beteende.

B. AI Powered Responses (Pro)

AI Provider - Väljer LLM-tjänst i backend.
API Key - Autentiseringsnyckel för vald leverantör.
Load Models - Hämtar tillgängliga modeller för leverantören/nyckeln.
AI Model - Modell som används för svarsgenerering.
Test Connection - Verifierar att nyckel/modell/leverantör fungerar.
Max Tokens - Maximal längd på AI-svar.
System Instructions - Definierar botens beteende, ton och regler.
AI Disclaimer - Valfri informationsrad under AI-svar.

C. Vector Retrieval (RAG) (Pro)

Enable RAG - Tillåter hämtning från indexerat webbplatsinnehåll.
Use PostgreSQL pgvector - Aktiverar skalbar lagring/sökning av vektorer.
Embedding Provider - Tjänst som omvandlar text till vektorer.
Embedding API Key - Autentisering för embedding-leverantör.
Fetch Models - Hämtar tillgängliga embedding-modeller.
Embedding Model - Modell för indexering och fråge-embeddings.
Test Embedding Connection - Verifierar att embedding-endpoint fungerar.
Crawl Root URL / Sitemap - Definierar crawlens startpunkter.
Max Pages / Max Depth - Styr crawl-omfattning och djup.
Chunk Size / Overlap - Styr textsegmentering för bättre retrieval-kvalitet.
Include / Exclude Patterns - Finjusterar vilka URL:er som crawlas.
Resume Mode - Hoppar över redan indexerade URL:er vid omcrawl.
Crawl Website Content - Startar indexeringsjobb.
RAG Ranking Mode - Styr rankningsstrategi (Balanced / Exact Product First).

2.5 FAQs-sidan

Add FAQ - Manuell Q&A med unikt nyckelord.
Edit/Delete FAQ - Underhåll och korrigering av befintliga svar.
Import File - Massimport av FAQ från TXT/CSV/CSB/DOCX.
Delimiter Option - Tolkar anpassade filformat (:, ,, | osv).
Duplicate Keyword Handling - Hoppa över eller suffixa dubbletter vid import.
Category Handling - Skapa saknade kategorier eller använd fallback-kategori.
Import Summary - Visar antal tillagda/avvisade/dubbletter.

2.6 Logs-sidan

Session Filters - Sök på sessionsnyckel, namn eller e-post.
Show Chat - Visar chatthistorik endast för vald session.
Leads Table - Visar insamlade kontaktuppgifter.
Pagination - Navigera i stora datamängder med kontroller uppe och nere.

2.7 Frontend-beteende

Widget Open - Användaren öppnar widgeten och går in i chatten.
Welcome/Categories - Introduktion och rekommendationer visas (om aktiverat).
User Query Handling:
- Free: FAQ + fuzzy match-flöde.
- Pro: FAQ + AI + RAG + handoff-regler.
Lead Collection - Namn/e-post-formulär visas när funktionen är aktiverad.
Logging - Sessioner/meddelanden/leads sparas för analys.

2.8 Felsökning

Widgeten syns inte - Kontrollera embed-kod, domänpolicy och webbläsarkonsol.
Korta AI-svar - Prova annan modell/leverantör, höj max tokens, testa leverantörens metadata.
RAG svarar inte - Bekräfta crawl, embedding-inställningar och rankingläge.
Installation blockerad - Verifiera installationstoken och lock/maintenance-beteende.

2.9 Rekommenderad utrullning

Börja med FAQ + kategorier - Bygg en stabil bas för svar.
Aktivera fuzzy match - Öka tolerans för variation i frågor.
Aktivera lead capture - Börja samla kvalificerade leads.
(Pro) Aktivera AI - Hantera bredare naturligt språk.
(Pro) Aktivera RAG - Förankra svar i eget webbplatsinnehåll.
(Pro) Aktivera handoff - Eskalera komplexa ärenden till människor.
Slutför säkerhet + driftsätt - Lås policy och gå live.