Passer au contenu principal

Dépannage

Utilisez cette page lorsque le widget est installé mais ne se comporte pas comme prévu.

Le widget n'apparaît pas​

Vérifiez d'abord la console du navigateur. ChattyBox y signale des attributs requis manquants.

Causes courantes :

  • Le script est absent à la fois du HTML déployé et du DOM en direct.
  • Le script a été ajouté au mauvais modèle, mise en page, conteneur de gestionnaire de balises ou zone de code CMS.
  • Le chargement du script dépend d'une règle de consentement ou d'un déclencheur de gestionnaire de balises qui ne s'est pas activé.
  • Le composant de l’application qui monte le loader ne s’exécute pas sur cette route.
  • Une politique de sécurité du contenu bloque https://chattybox.ai/widget.js.
  • CSS ou un autre widget chevauche le lanceur.
  • La configuration déployée contient widget.enabled: false.

La plus petite correction :

  1. Ouvrez la page publique déployée dans une fenêtre de navigation privée.
  2. Recherchez chattybox.ai/widget.js dans la source de la page et dans le panneau Elements du navigateur ; un loader injecté par le SDK ou par JavaScript peut n’apparaître que dans le DOM en direct.
  3. Confirmez que le script apparaît une fois et inclut data-api-key et data-api-url.
  4. Déplacez le script vers le pied de page global, la présentation de l'application, la racine Docusaurus ou le déclencheur GTM Toutes les pages s'il est manquant.

Pour les projets gérés par configuration, widget.enabled: false empêche le widget hébergé de s’initialiser et fait renvoyer 403 Widget is disabled aux requêtes publiques POST /chat, y compris celles du SDK headless. Modifiez ce paramètre via le workflow de déploiement de configuration, et non en faisant tourner la clé publique. Supprimer le script après l’initialisation ne retire pas le widget déjà affiché.

data-api-url manquant​

Le widget se ferme plus tôt lorsque data-api-url est manquant.

Utilisez l'extrait complet du tableau de bord ou ajoutez l'attribut requis :

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Utilisez l’URL API affichée dans votre tableau de bord plutôt que de la deviner. En production, elle doit être une URL stable au format https://...convex.site/chat.

Erreur générique 401 Invalid API key​

Pour des raisons de sécurité, les API du widget renvoient la même réponse générique 401 Invalid API key pour une clé publique inconnue, expirée ou rejetée en raison de son origine. Ne déduisez pas la cause de cette réponse.

Causes courantes :

  • La clé publique du widget n'a pas été copiée correctement.
  • La clé a été supprimée, a expiré ou provient d’un déploiement backend différent de celui de l’URL API.
  • Le projet ou le propriétaire associé à la clé est en cours de suppression.
  • La restriction d’origine facultative est activée pour la clé, mais l’origine actuelle du site n’est pas autorisée.

Correctifs :

  1. Ouvrez le projet dans le tableau de bord ChattyBox.
  2. Ouvrez Installer → Installation sur le site web, saisissez l’URL du site et copiez un extrait admissible si l’un est disponible.
  3. Sous Clés et domaines sur la même page, choisissez Modifier les origines pour la clé de l’extrait installé. Si Restreindre cette clé à des origines spécifiques est activé, ajoutez l’origine exacte qui sert la page, ou désactivez la restriction facultative. Le protocole, le nom d’hôte et le port doivent tous correspondre : https://example.com, https://preview.example.com et http://localhost:3000 sont des origines différentes. Il n’est pas nécessaire d’ajouter une entrée distincte pour chaque chemin.
  4. Redéployez ou republiez le site et testez à nouveau dans une fenêtre de navigation privée.

Une clé valide associée à un autre chatbot sur le même backend sélectionne normalement cet autre chatbot au lieu de produire une erreur 401 ; vérifiez le projet si les réponses ne sont pas pertinentes. Les noms de clé comme « production » et « staging » ne définissent pas les environnements. Si l’en-tête Origin est présent, l’API HTTP l’utilise ; elle ne se rabat sur l’origine de Referer que si Origin est absent. Si Origin est présent mais ne correspond pas à une origine autorisée, une valeur Referer autorisée ne le remplace pas. Une clé restreinte rejette toute requête dont l’origine ainsi sélectionnée est absente, invalide ou non autorisée. Les restrictions d’origine ne remplacent pas l’authentification des visiteurs.

Limites de messages ou de débit​

Consultez Facturation et utilisation à l’adresse /settings/account pour vérifier l’utilisation des messages, le forfait et les budgets PAYG facultatifs des forfaits Pro/Business. Le chat de test et le chat public consomment tous deux l’allocation de messages partagée du propriétaire. Supprimer des conversations ou créer une autre clé ne réinitialise pas cette allocation.

Les erreurs d’allocation mensuelle et les limites de débit à court terme sont différentes. Pour les réponses HTTP 429, respectez Retry-After lorsqu’il est fourni au lieu de réessayer sans cesse. En cas de limite mensuelle de messages, attendez la réinitialisation de l’allocation ou modifiez le forfait ou le budget PAYG admissible. Conversations → Historique contient l’historique des conversations, pas une console d’erreurs par requête ; inspectez les échecs HTTP dans le panneau Réseau du navigateur.

Mauvaise langue​

Vérifiez d’abord Personnaliser → Apparence pour les paramètres de langue du widget. Dans le code source actuel, le widget hébergé choisit la langue de son interface dans cet ordre :

  1. data-locale seulement si Autoriser le remplacement par script est activé.
  2. En mode Fixe, la langue par défaut configurée.
  3. En mode Détection automatique, <html lang>, puis la langue du navigateur, puis la langue par défaut.

Les valeurs de locale non prises en charge sont ignorées. L’anglais est utilisé en dernier recours si aucun candidat n’est pris en charge ; la langue par défaut est l’anglais au départ.

Correctifs :

  • Pour la détection automatique, choisissez Détection automatique et supprimez un data-locale incorrect ou désactivez les remplacements par script.
  • Définissez <html lang="de">, <html lang="fr"> ou le code de langue correspondant sur les pages localisées.
  • Pour imposer la langue configurée, choisissez Fixe et désactivez Autoriser le remplacement par script. Si les remplacements sont autorisés, data-locale reste prioritaire sur le mode Fixe.
  • Vérifiez que les paramètres sont enregistrés, réinitialisez le widget installé pour qu’il récupère les changements de configuration du tableau de bord, puis testez à nouveau. Dans le code source actuel, le loader hébergé widget.js v16 peut mettre à jour les libellés appartenant au produit lorsque la modification de <html lang> ou de data-locale sur le loader change la locale résolue. Vérifiez la version du loader déployé avant de compter sur ces mises à jour en direct ; ce comportement du loader hébergé est distinct de celui du SDK npm publié 0.1.4. Une valeur locale fournie à mountWidget() devient data-locale et suit les mêmes règles du projet.
  • Si le widget est indisponible, vérifiez la requête /widget-config et la clé publique. Dans le code source actuel, le widget hébergé widget.js v16 reste indisponible si la récupération de configuration échoue, au lieu de démarrer avec les paramètres par défaut. Vérifiez la version du loader déployé avant de compter sur ce comportement.
  • Indexez chaque version linguistique nécessaire si les réponses citent ou récupèrent du contenu dans la mauvaise langue. Le générateur détecte la langue à partir de la question, indépendamment de la langue de l’interface du widget ; le mode Fixe ne force pas la langue de réponse et ne traduit pas le contenu source. Sans message personnalisé assistant.fallbackMessage, le message de repli intégré en cas de contenu manquant utilise la langue détectée dans la question lorsqu’elle peut être déterminée ; si la détection est incertaine, il utilise la langue de l’interface du widget, avec l’anglais comme dernier recours.

Aucune citation ou réponse faible​

ChattyBox utilise le contenu source récupéré pour générer les réponses. Des citations manquantes ou des réponses faibles peuvent résulter d’un contenu source absent ou inadapté, de problèmes de récupération ou d’échecs de génération ; elles ne permettent pas à elles seules d’identifier la cause. Un chatbot RAG ancré bénéficie d’un contenu source récupéré clair, mais une citation seule ne vérifie pas une réponse. Comparez chaque affirmation importante à la page citée.

Correctifs :

  • Posez la même question dans le chat de test du tableau de bord et comparez les pages citées.
  • Assurez-vous que la page source est publique et incluse dans l'analyse.
  • Ajoutez des titres clairs, des exemples, des FAQ et un texte de réponse directe à la page source.
  • Évitez de vous fier aux captures d'écran, aux vidéos, au balisage masqué exclu, au contenu disponible uniquement via JavaScript ou aux iframes comme seule source.
  • Re-scrapez la page mise à jour lorsque le délai de réactualisation le permet, attendez le traitement des embeddings, puis testez à nouveau.
  • Recherchez les avertissements Partiellement indexé : le texte dépassant la limite de 512 KiB par page n’est pas conservé. Scindez les longues pages plutôt que de reconstruire sans cesse le même texte tronqué.
  • Formulez des questions claires et autonomes lorsque c’est possible. Le générateur peut recevoir jusqu’à 12 messages enregistrés récents, limités chacun à 2 000 caractères ; il ne reçoit pas la transcription complète de la conversation.

Persona ajoute des instructions propres au site aux règles intégrées d’ancrage sur les sources ; il ne peut pas fournir le contenu indexé manquant ni remplacer le message de repli en cas de contexte manquant ou de lacune de contenu lorsque celui-ci est déclenché. Le détecteur de lacunes de contenu est heuristique et peut ne pas repérer toutes les réponses non étayées. Ce message de repli est configuré séparément par assistant.fallbackMessage dans la configuration comme code.

Pages non grattées ou contenu périmé​

Causes courantes :

  • La page est absente du plan du site soumis.
  • Le mode URL manuel n’incluait pas la page.
  • La page bloque les requêtes HTTP ordinaires, nécessite une authentification, renvoie un CAPTCHA/une erreur, redirige vers une cible bloquée, ou est exclue par la sélection et les budgets.
  • Le contenu de la page a changé après la dernière exploration.
  • Le contenu est uniquement rendu par JavaScript ou se trouve hors de la racine de contenu sémantique sélectionnée.
  • Les URL sélectionnées dépassent l’allocation de pages, le budget mensuel de réactualisation est épuisé ou une règle d’inclusion/d’exclusion les filtre.

Correctifs :

  1. Confirmez que la page s'ouvre publiquement dans une fenêtre de navigateur privée.
  2. Utilisez le mode plan du site pour une large couverture ou des URL manuelles pour un ensemble organisé.
  3. Soumettez l'URL canonique plutôt qu'une URL de suivi, une URL de redirection ou une URL de connexion.
  4. Après publication des modifications, relancez l’exploration lorsque le délai de réactualisation le permet : au moins sept jours depuis la création du dernier job sur Free, ou 24 heures sur les forfaits payants, même si ce job a échoué.
  5. Dans Base de connaissances → Pages, développez Historique des imports lorsque des tâches existent et sélectionnez une tâche sous Tâches de scraping. Comparez ses nombres de pages enregistrées et sélectionnées ainsi que la liste Pages avec les URL attendues. Terminé peut inclure des URL ignorées ou en échec ; Terminé avec des avertissements signale précisément du texte de page conservé partiellement, pas tous les échecs d’exploration. L’interface ne fournit pas de liste complète des échecs par URL.

ChattyBox peut lire robots.txt pour y découvrir des déclarations de sitemap sur la même origine, mais n’applique pas ses directives d’exploration. Ne considérez pas robots.txt comme un contrôle d’accès. ChattyBox suit les redirections HTTP sûres ; une redirection ne constitue donc pas à elle seule un échec. Ne supprimez pas les protections d’accès et ne rendez pas public un contenu privé pour le faire explorer.

Si une URL a été retirée du site ou de la sélection de sources, sa page enregistrée peut toujours être utilisée. Supprimez-la aussi dans Base de connaissances → Pages, en plus de l’exclure des futures découvertes. Reconstruire l'index utilise le texte enregistré et ne récupère pas à nouveau le contenu sur le réseau ; cette opération a son propre délai selon le forfait et consomme le budget mensuel de réactualisation.

Les paramètres ne s’enregistrent pas​

Les modifications des détails du chatbot et des paramètres des sources sont enregistrées automatiquement. Vérifiez l’état de l’enregistrement, corrigez les erreurs de validation ou réessayez après un échec avant de continuer. L’URL du site doit être enregistrée dans le tableau de bord même si vous saisissez des URL manuelles. La découverte et l’enregistrement automatique ne lancent pas l’importation : vérifiez les pages sélectionnées et démarrez explicitement l’importation.

Si le projet est verrouillé par configuration, la configuration doit être déployée via le workflow CLI. Ce verrouillage est irréversible ; les enregistrements de Persona, la configuration d’exploration, Lancer le scraping, la suppression de contenu et la reconstruction de l’index sont refusés, même si une commande reste visible. Seule la préférence de marque reste modifiable dans le tableau de bord pour la configuration du widget hébergé, sous réserve du forfait. Les clés publiques du widget et les jetons de déploiement sont des identifiants distincts.

Si un projet est introuvable ou si l’accès est refusé, vérifiez que vous êtes connecté en tant que propriétaire. Une clé de widget, un jeton de déploiement ou l’appartenance à une organisation ne donne pas les droits de propriétaire dans le tableau de bord. Dans Conversations, Analyses et Questions sans réponse sont incluses dans les offres Pro et Business ; les vues indisponibles affichent une invitation à passer à une offre supérieure. Historique est disponible avec tous les forfaits.

Toujours coincé​

Recueillez ces informations avant de contacter l'assistance :

  • L'URL de la page publique où le widget doit apparaître.
  • Une capture d'écran ou une copie de toute erreur de la console du navigateur.
  • Si la page utilise un simple HTML, Next.js, Docusaurus, WordPress, un CMS ou Google Tag Manager.
  • Indique si l'extrait inclut data-api-key et data-api-url.
  • Une question test qui devrait fonctionner et la page source qui y répond.