Ce guide couvre les éditions Free et Pro au même endroit. Lorsqu’une fonctionnalité est réservée à Pro, elle est marquée (Pro).

1. Installation

1.1 Prérequis

Node.js 18+ - Environnement requis pour exécuter le serveur backend du chatbot.
npm - Requis pour installer les dépendances du projet.
Navigateur moderne - Requis pour accéder au panneau admin et tester le comportement du widget.
PostgreSQL 13+ (optionnel en Pro) - Requis uniquement si vous choisissez le mode de stockage PostgreSQL.
pgvector (optionnel en Pro) - Requis pour la recherche de similarité vectorielle PostgreSQL en mode RAG.
Ollama (optionnel en Pro) - Requis uniquement si vous souhaitez des embeddings locaux sans coût API.

1.2 Télécharger et préparer

Extraire le package - Décompressez stella-ai-chatbot-free ou stella-ai-chatbot-pro.
Ouvrir le dossier dans le terminal - Exécutez toutes les commandes d’installation/démarrage depuis ce répertoire.
Installer les dépendances - Télécharge toutes les bibliothèques backend nécessaires.

npm install

1.3 Configurer l’environnement

Créer .env - Copiez .env.example vers .env.
Définir les variables obligatoires:
- NODE_ENV - Définit le mode d’exécution (development ou production).
- APP_SECRET - Utilisé pour signer/vérifier les tokens et sessions sécurisés.
- ADMIN_USER - Nom d’utilisateur admin.
- ADMIN_PASS - Mot de passe admin.
- INSTALL_TOKEN - Protège l’installateur contre les accès non autorisés.
- CORS_ORIGINS / ALLOWED_ORIGINS - Contrôle quels origins peuvent appeler les API.
- DATA_ENCRYPTION_KEY - Utilisé pour chiffrer les données sensibles (si pris en charge).
Variables optionnelles:
- PORT - Port serveur (la plateforme peut le remplacer dynamiquement).
- TRUST_PROXY=true - Active une détection IP correcte derrière reverse proxy/CDN.

1.4 Démarrer l’application

npm start

/install - Assistant de configuration initiale.
/admin - Connexion admin et tableau de bord.

1.5 Étapes d’installation

Ouvrir l’installateur - /install initialise le système chatbot.
Saisir le token d’installation - Confirme une installation autorisée.
Sélectionner le mode de stockage:
- Free: stockage JSON.
- Pro: JSON ou PostgreSQL.
Terminer l’installation - Crée les paramètres/valeurs par défaut requis.
install.lock généré - Empêche une réinstallation accidentelle et se trouve dans le dossier data.

1.6 Intégrer le widget sur n’importe quel site

Ouvrir la section Embed Code - Génère le script d’intégration frontend.
Copier le script - Inclut le chargeur de widget et l’URL API de base.
Coller avant </body> - Garantit le chargement du widget après le contenu.
Rafraîchir le site - Vérifie que le chatbot apparaît et fonctionne.

1.7 Checklist production

Activer HTTPS - Protège le trafic et les identifiants.
Utiliser des secrets robustes - Empêche la compromission de tokens/sessions.
Restreindre les domaines - Évite l’usage abusif du widget/API sur des sites non autorisés.
Protéger l’installateur - Bloque les attaques de réinstallation publique.
Activer CSRF/contrôles sécurité - Protège les écritures admin.
Définir une politique de rétention - Garde les logs gérables et conformes.

2. Guide utilisateur (Étape par étape)

2.1 Connexion admin

Ouvrir /admin - Accède à la page d’entrée admin.
Se connecter - Utilise les identifiants de .env.
Naviguer dans le menu - Overview, Settings, FAQs, Logs.

2.2 Page Overview

Statistiques d’usage - Affiche un résumé d’activité du chatbot.
Matched vs unmatched - Affiche la tendance de qualité des réponses.
Top matched keywords - Identifie les requêtes bien traitées.
Top unmatched questions - Montre les lacunes FAQ/IA à améliorer.

2.3 Page Settings

A. Core Identity

Chatbot Name - Titre affiché dans l’en-tête du chat.
Avatar Upload - Image de marque affichée dans le launcher et le chat.
Avatar Shape - Détermine si l’avatar est rond ou carré.
Show Live Preview - Active/désactive la prévisualisation en temps réel dans l’admin.

B. Messaging & Engagement

Welcome Message - Message affiché à l’ouverture du chat.
No Match Message - Réponse de secours si aucune réponse n’est trouvée.
Fuzzy Match - Associe des mots-clés/questions proches sans correspondance exacte.
Fuzzy Threshold - Définit le niveau de tolérance de la correspondance floue.
Lead Capture - Collecte nom/email avant ou pendant la conversation.
Lead Capture Prompt - Message affiché pour demander les informations utilisateur.

C. Widget Appearance

Widget Position - Place le launcher à gauche ou à droite.
Widget Size - Contrôle la taille visuelle du launcher.
Brand/Theme Colors - Harmonise le widget avec la charte du site.
Avatar Size - Contrôle la taille de l’avatar dans l’UI de chat.
Animation - Ajoute des effets comme pulse/shake/float.
Chatbox Width/Height - Contrôle les dimensions du panneau de conversation.

D. System & Performance

Items Per Page - Taille de pagination des tableaux admin.
Log Retention Days - Nombre de jours de conservation des logs.
Auto Cleanup - Supprime automatiquement les anciennes données selon la règle de rétention.
Enforce HTTPS - Bloque les requêtes non HTTPS (hors localhost).
Enforce Admin CSRF - Exige un token CSRF pour les écritures admin.

E. Categories

Add Category - Crée de nouveaux groupes pour FAQ/flux de chat.
Recommended Categories - Jusqu’à 3 catégories affichées en priorité dans le widget.
Delete Category - Supprime les catégories inutilisées (ou applique fusion/réaffectation).

F. Embed Code

API Base URL - Définit l’URL backend utilisée par le script widget.
Allowed Widget Domains - Restreint les domaines où le widget peut fonctionner.
Widget Domain Policy - restricted impose une liste de domaines autorisés.
Regenerate / Copy Code - Régénère et copie le script d’intégration.

2.4 Fonctionnalités Pro dans Settings (Pro)

A. Human Handoff (Pro)

Enable Handoff - Active l’escalade vers un support humain.
Escalate After Unmatched - Nombre d’échecs avant escalade.
Handoff Message - Message affiché lors du déclenchement de l’escalade.
Support URL - Lien vers le support humain.
Business Hours - Plage horaire optionnelle pour le comportement handoff.

B. AI Powered Responses (Pro)

AI Provider - Sélectionne le fournisseur LLM backend.
API Key - Clé d’authentification du fournisseur.
Load Models - Charge les modèles disponibles pour ce fournisseur/clé.
AI Model - Modèle utilisé pour générer les réponses.
Test Connection - Vérifie la configuration fournisseur/modèle/clé.
Max Tokens - Longueur maximale de sortie des réponses IA.
System Instructions - Définit comportement, ton et règles du bot.
AI Disclaimer - Message d’avertissement optionnel sous les réponses IA.

C. Vector Retrieval (RAG) (Pro)

Enable RAG - Permet la récupération depuis le contenu indexé du site.
Use PostgreSQL pgvector - Active le stockage/recherche vectorielle scalable.
Embedding Provider - Service qui convertit le texte en vecteurs.
Embedding API Key - Authentification du fournisseur d’embeddings.
Fetch Models - Charge les modèles d’embedding disponibles.
Embedding Model - Modèle utilisé pour indexation et requêtes.
Test Embedding Connection - Vérifie le bon fonctionnement de l’endpoint embedding.
Crawl Root URL / Sitemap - Définit les points de départ du crawl.
Max Pages / Max Depth - Contrôle l’ampleur et la profondeur du crawl.
Chunk Size / Overlap - Contrôle la segmentation du texte pour une meilleure qualité RAG.
Include / Exclude Patterns - Contrôle fin des URLs à crawler.
Resume Mode - Ignore les URLs déjà indexées lors d’un recrawl.
Crawl Website Content - Lance le job d’indexation.
RAG Ranking Mode - Contrôle la stratégie de classement (Balanced / Exact Product First).

2.5 Page FAQs

Add FAQ - Création manuelle Q&A avec mot-clé unique.
Edit/Delete FAQ - Maintient et corrige les réponses existantes.
Import File - Import en masse depuis TXT/CSV/CSB/DOCX.
Delimiter Option - Analyse les formats personnalisés (:, ,, |, etc).
Duplicate Keyword Handling - Ignore ou suffixe les doublons lors de l’import.
Category Handling - Crée les catégories manquantes ou applique une catégorie fallback.
Import Summary - Affiche les compteurs ajoutés/rejetés/doublons.

2.6 Page Logs

Session Filters - Recherche par clé de session, nom ou email.
Show Chat - Ouvre l’historique uniquement de la session sélectionnée.
Leads Table - Affiche les coordonnées visiteurs collectées.
Pagination - Navigue efficacement dans les gros volumes via contrôles haut/bas.

2.7 Comportement frontend

Widget Open - L’utilisateur ouvre le launcher et entre dans le chat.
Welcome/Categories - Introduction et recommandations s’affichent (si activé).
User Query Handling:
- Free: flux FAQ + fuzzy match.
- Pro: FAQ + IA + RAG + règles de handoff.
Lead Collection - Formulaire nom/email affiché quand activé.
Logging - Sessions/messages/leads enregistrés pour l’analytique.

2.8 Dépannage

Widget non visible - Vérifiez embed code, policy de domaine et console navigateur.
Réponses IA courtes - Essayez un autre modèle/fournisseur, augmentez max tokens, vérifiez metadata fournisseur.
RAG ne répond pas - Vérifiez crawl, config embedding et mode de ranking.
Installation bloquée - Vérifiez install token et comportement lock/maintenance.

2.9 Plan de déploiement recommandé

Commencer par FAQ + catégories - Construire une base de réponses fiable.
Activer fuzzy match - Améliorer la tolérance aux variations de questions.
Activer lead capture - Commencer la collecte de contacts qualifiés.
(Pro) Activer IA - Gérer des requêtes en langage naturel plus larges.
(Pro) Activer RAG - Ancrer les réponses dans votre propre contenu.
(Pro) Activer handoff - Escalader les besoins complexes vers des humains.
Finaliser sécurité + déployer - Verrouiller les politiques et passer en production.