🤖 Guide d'intégration du bot web

Ce guide explique comment créer un bot depuis l'interface Service Client (http://localhost:3000/customer-service) et l'intégrer sur n'importe quel site via le widget JavaScript hébergé dans public/chat-widget.js.

---

1. Créer et configurer un bot

1. Lancez l'application (npm run dev) puis ouvrez http://localhost:3000/customer-service.
2. Cliquez sur « Nouveau bot ».
3. Renseignez les champs essentiels :
   • Nom & description (affichés dans le widget)
   • Message d'accueil et Instructions système pour guider l'IA
   • Couleurs / branding via l'onglet Apparence
4. Activez le canal « Site web ».
5. Enregistrez. Le bot obtient un botId et des paramètres d'intégration.

Astuce : utilisez la prévisualisation intégrée dans la page pour valider le rendu avant d’exporter le code.

---

2. Récupérer le code d'intégration

Sur la fiche du bot, ouvrez l’onglet Intégration > Site web :

1. Copiez l’URL de votre instance (ex. https://app.octobot.fr).
2. Copiez le snippet généré (inclus ci-dessous pour référence).
3. Collez-le juste avant la balise </body> de votre site.

<!-- Octobot – Widget Service Client -->
<script src="https://APP_DOMAIN/chat-widget.js"></script>
<script>
  ChatWidget.init({
    botId: 'BOT_ID_FOURNI',
    authUrl: '/api/auth/token',      // Laisse la valeur par défaut dans 99% des cas
    chatUrl: '/api/chatbot',
    widgetUrl: '/api/widget',
    color: '#6366f1',
    position: 'bottom-right',
    widgetButtonText: 'Besoin d’aide ?',
    welcomeMessage: 'Bonjour ! Comment puis-je vous aider ?'
  });
</script>

Remplacez APP_DOMAIN par le domaine où Octobot est déployé (pendant le développement : http://localhost:3000). Le widget charge automatiquement la configuration distante du bot (widgetUrl) et n’a besoin d’aucune dépendance supplémentaire.

---

3. Paramètres disponibles

Clé	Description	Valeur par défaut
botId	Identifiant UUID du bot (copié depuis l’interface)	(obligatoire)
authUrl	Endpoint qui délivre un jeton sécurisé au widget	/api/auth/token
chatUrl	Endpoint principal pour envoyer les messages	/api/chatbot
widgetUrl	Endpoint qui renvoie le thème/branding du bot	/api/widget
color / widgetColor	Couleur principale des bulles et du bouton	#6366f1
position	bottom-right ou bottom-left	bottom-right
widgetButtonStyle	icon, text, icon-text	icon-text
widgetButtonShape	pill, square, circle	pill
widgetButtonIcon	message-circle, help, bot, etc.	message-circle
welcomeMessage	Premier message affiché à l’utilisateur	Bonjour ! ...

Tous les paramètres sont optionnels sauf botId ; le widget fusionne vos valeurs avec celles stockées sur widgetUrl.

---

4. Bonnes pratiques & débogage

• CORS / domaines autorisés : vérifiez que le domaine final (prod/staging) est bien ajouté dans la section Sécurité du bot pour éviter les erreurs 401.
• HTTPS recommandé : en production, servez le widget via HTTPS pour éviter les avertissements navigateur.
• Rafraîchissement du token : chat-widget.js régénère automatiquement le jeton d’accès avant expiration ; aucun cron n’est nécessaire.
• Logs navigateur : en cas de message « Auth failed » ou Config fetch error, ouvrez la console pour confirmer que les routes /api/auth/token, /api/widget/:botId et /api/chatbot/:botId/chat répondent sans erreur.
• Mode local : utilisez http://localhost:3000/chat-widget.js + botId d’une base locale. Les conversations seront stockées en SQLite (dev) ou PostgreSQL (prod).

---

5. Checklist avant mise en ligne

• Bot actif et testé depuis http://localhost:3000/customer-service
• Domaine final autorisé dans les paramètres du bot
• Script chat-widget.js accessible publiquement
• Snippet intégré juste avant </body> sur votre site
• Tests réalisés sur mobile et desktop

Une fois ces étapes validées, votre bot IA Octobot est disponible 24/7 sur votre site web. 🎉