Guide d'installation et d'utilisation de Stella AI Chatbot

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. Installation1.1 PrérequisNode.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éparerExtraire 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 install1.3 Configurer l’environnementCré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’applicationnpm start/install - Assistant de configuration initiale./admin - Connexion admin et tableau de bord.1.5 Étapes d’installationOuvrir 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 siteOuvrir 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 productionActiver 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 adminOuvrir /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 OverviewStatistiques 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 SettingsA. Core IdentityChatbot 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 & EngagementWelcome 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 AppearanceWidget 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 & PerformanceItems 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. CategoriesAdd 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 CodeAPI 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 FAQsAdd 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 LogsSession 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 frontendWidget 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épannageWidget 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.