Guide de Stella AI Chatbot couvrant l'automatisation FAQ, capture de leads, conversations IA, RAG, transfert humain et analytiques Pro pour tout site.

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.

Stella AI Chatbot : Guide d'Installation et Utilisateur