Passer au contenu principal

:::note État des versions Dans ce dépôt, le loader hébergé widget.js du code source actuel est en v16. Cela ne garantit pas que la version déployée soit v16 : vérifiez le loader effectivement servi avant de vous appuyer sur ces comportements. Le SDK npm publié 0.1.4 a une version distincte de celle du loader hébergé. :::

Personnalisation du widget hébergé

Personnalisez l’interface prête à l’emploi chargée par https://chattybox.ai/widget.js. Pour les exemples d’installation de référence par framework et plateforme, consultez les Guides d’installation.

Avant de personnaliser​

Créez le projet, indexez son contenu et vérifiez des réponses représentatives dans Tester le chatbot avant de consacrer du temps à la présentation. Consultez Prise en main pour découvrir la séquence complète.

Configurer le widget hébergé​

  1. Accédez à votre tableau de bord et sélectionnez votre projet.
  2. Ouvrez Personnaliser → Apparence pour modifier l’apparence, la marque et les réglages de Langue du widget.
  3. Vérifiez l’état de l’enregistrement automatique ; corrigez les erreurs de validation ou réessayez les enregistrements échoués avant de tester le widget installé.

Le code d’installation et les clés publiques se trouvent sous Installer. Lorsque vous êtes prêt à installer le widget :

  1. Ouvrez Installer → Clés et domaines pour examiner ou créer une clé publique de navigateur et vérifier ses réglages d’origine.
  2. Sous Installer → Installation sur le site web, choisissez une clé et copiez le snippet généré. La préparation d’une installation pour un site web peut déjà restreindre la clé à l’origine exacte saisie. Les clés créées sans restriction fonctionnent depuis toutes les origines : vérifiez la clé avant de l’utiliser en préproduction ou sur localhost.
  3. Vous pouvez activer une restriction d’origine exacte comme protection supplémentaire. Une origine comprend le schéma, l’hôte et le port ; ces restrictions ne sont pas une authentification des visiteurs.
  4. Suivez les Guides d’installation correspondant à votre plateforme.
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-api-url="https://adorable-woodpecker-629.convex.site/chat"
async
></script>
conseil

Les changements enregistrés s’appliquent à la prochaine initialisation du widget ; les pages déjà ouvertes ne sont pas mises à jour en direct. Vérifiez l’état d’enregistrement automatique avant de recharger. La prévisualisation du tableau de bord est une maquette, pas le widget hébergé.


Personnalisation visuelle​

L’éditeur ajuste les couleurs prises en charge, la position, l’icône et le texte sans modifier le code. Vérifiez toujours le résultat dans le widget hébergé : la prévisualisation et le loader ne sont pas identiques.

Commandes du tableau de bord​

  1. Couleur d’accent – Choisissez la couleur principale de votre marque. Elle s’applique au bouton d’ouverture, aux éléments mis en évidence et aux messages des utilisateurs.

  2. Position du widget – Choisissez où le widget apparaît à l’écran.

  3. Titre de l’en-tête – Définissez le titre affiché en haut de la fenêtre de chat.

  4. Message de bienvenue – Personnalisez le premier message que les visiteurs voient lorsqu’ils ouvrent le chat.

  5. Marque ChattyBox – Les offres Starter et supérieures peuvent désactiver le pied de page « Propulsé par ChattyBox ». La marque reste obligatoire avec l’offre Free.

L’éditeur fournit aussi les commandes Arrière-plan du widget, Couleur du texte et l’icône (robot, emoji, URL d’image ou image téléversée). Le contrôle Taille de l’icône n’apparaît que si vous choisissez une URL d’image ou téléversez une image. Les icônes téléversées sont limitées à 512 KiB et aux formats PNG, JPEG, WebP, SVG, GIF ou ICO. Dans le code source actuel du loader hébergé v16, iconSize ajuste la taille du bouton de lancement et de l’icône. Vérifiez la version effectivement servie avant de vous appuyer sur ce comportement.

note

Pour les projets verrouillés par la configuration, les réglages d’apparence et de langue sont gérés par config-as-code. Les projets qui disposent des droits requis peuvent toujours modifier séparément la préférence de marque. Vérifiez l’état d’enregistrement automatique, puis rechargez la page installée pour contrôler les changements.

Valeurs par défaut de la configuration​

Le tableau décrit les valeurs renvoyées par le code source actuel lorsqu’une requête publique de configuration du widget aboutit et qu’aucune valeur personnalisée n’est définie. Il ne garantit pas la version déployée ; vérifiez le loader effectivement servi avant de vous appuyer sur un comportement lié à sa version.

ChampValeur par défaut
enabledtrue, sauf si le widget est désactivé pour le projet
themeColor#3b82f6
chatBgColor#0f172a
textColor#f8fafc
positionbottom-right ; les quatre coins sont pris en charge
iconType, iconSizedefault, medium ; le loader hébergé v16 du code source actuel utilise cette taille pour le bouton de lancement et l’icône
iconEmoji, iconUrl💬, null
headerTitleChat with us (valeur par défaut de l’API)
welcomeMessageHi! 👋 How can I help you today? (valeur par défaut de l’API)
showBrandingtrue ; toujours activé pour les projets Free
localeMode, defaultLocale, allowLocaleOverrideauto, en, true (valeurs par défaut)

Options avancées​

Réglages du tableau de bord et attributs du script​

La plupart des comportements du widget doivent être gérés depuis le tableau de bord afin de ne pas avoir à redéployer votre site pour de simples changements.

Utilisez le tableau de bord pour les couleurs, la position, l’icône, le titre de l’en-tête, le message de bienvenue, les langues par défaut, la gestion des clés publiques, le scraping et Analytics.

Si vous activez une restriction d’origine pour une clé publique, synchronisez ses origines exactes avec les sites où le widget est installé. La correspondance inclut le schéma, l’hôte et le port. Les clés de navigateur sont publiques ; les restrictions d’origine sont une protection supplémentaire facultative, pas une authentification des visiteurs.

Utilisez les attributs du script pour les valeurs dont le widget a besoin au chargement de la page. Le loader du code source actuel observe aussi les modifications de data-locale, comme indiqué ci-dessous :

  • data-api-key identifie la clé publique du widget.
  • data-api-url indique au widget où envoyer les requêtes. En production, il s’agit d’une URL stable https://...convex.site/chat fournie par votre tableau de bord.
  • data-locale demande une langue d’interface précise si le projet autorise les remplacements. Le loader du code source actuel observe également les modifications de cet attribut.
  • Dans le code source actuel du loader hébergé v16, data-color et data-position remplacent respectivement la couleur d’accent et la position enregistrées après une récupération réussie de la configuration ; ces attributs peuvent masquer les changements ultérieurs du tableau de bord. Préférez les valeurs du tableau de bord et vérifiez le loader effectivement servi avant de vous appuyer sur ce comportement.
  • data-debug="true" active les diagnostics de console ; cette option est désactivée par défaut.

Échecs de chargement​

Dans le code source actuel du loader hébergé v16, un échec ou une réponse invalide lors de la récupération de la configuration rend le widget indisponible : aucune interface de remplacement n’est affichée. Une configuration récupérée avec enabled: false empêche également l’affichage, et l’API de chat rejette les requêtes vers un widget désactivé avec HTTP 403, y compris celles du SDK. Vérifiez la version effectivement déployée avant de vous appuyer sur ce comportement.

Un échec de récupération des traductions est différent : il ne survient qu’après le chargement réussi de la configuration. Le widget peut alors s’afficher avec ses libellés anglais intégrés. Les libellés manquants d’un catalogue utilisent également les valeurs anglaises par défaut.

Lorsque le loader fonctionne sans SDK exposé sur la page, le loader hébergé v16 du code source actuel demande la configuration avec Authorization: Bearer et ne réessaie qu’une fois avec la clé dans le paramètre de requête apiKey, uniquement après HTTP 400. Le SDK publié 0.1.4 utilise le même fallback limité à la configuration uniquement si la page expose window.ChattyboxSDK. Le loader v16 réessaie séparément les requêtes GET de configuration et de traductions au démarrage en cas d’échec réessayable. Les messages de chat utilisent le transport propre au loader hébergé. Pour le montage via le SDK, le SDK publié 0.1.4 ne partage que des options identiques et refuse une clé, un endpoint, une URL de script, une locale ou un réglage de debug différent tant que tous les handles correspondants n’ont pas été supprimés. Vérifiez la version du loader effectivement servie avant de vous appuyer sur le comportement du code source actuel.

Pour un nouveau message, le loader hébergé du code source actuel v16 tente d’envoyer l’origine et le chemin de la page HTTP(S) actuelle pour les analyses Déclencheurs populaires. Il ne vérifie pas si la page est publique. Les contextes invalides ou trop longs sont omis ; les tentatives répétées gardent le contexte de la requête initiale. Les paramètres de requête, fragments et identifiants de connexion sont supprimés, mais le chemin peut contenir des identifiants sensibles. N’installez pas le widget sur des routes sensibles au seul motif que les paramètres de requête sont retirés.

Le widget respecte aussi prefers-reduced-motion, fournit un champ de message avec libellé et des annonces en direct, et présente les citations dans un panneau Sources accessible au clavier.

Le loader peut aussi envoyer les erreurs d’initialisation, de configuration, de traduction ou de chat à /widget-error, par beacon ou fetch. Ces rapports comprennent des détails d’erreur limités, la locale, la version et l’origine/le chemin de la page. Le mode debug n’est pas nécessaire. Vérifiez la version effectivement déployée avant de vous appuyer sur ces comportements.

Le chat renvoie des réponses JSON complètes, sans diffusion de tokens. Dans le code source hébergé v16, chaque message reçoit une clé d’idempotence, réutilisée lors des tentatives de transport, afin qu’une réponse déjà traitée puisse être rejouée sans traiter le message une seconde fois. Le loader effectue au plus 10 tentatives automatiques pour les erreurs réseau, les corps de réponses interrompus malgré une réponse réussie, HTTP 429, HTTP 5xx et les réponses 409 accompagnées d’un en-tête Retry-After lisible. Il ne programme pas de nouvelle tentative si le délai dépasserait le budget de 30 secondes ; ce budget n’est pas un délai maximal strict pour une requête déjà en cours. CORS peut masquer Retry-After. sendMessage() sans interface ne réessaie pas automatiquement. Vérifiez la version déployée avant de vous fier à ces tentatives.

L’état de la conversation reste en mémoire dans l’instance du widget et disparaît au rechargement ou à la réinitialisation ; les messages déjà enregistrés sur le serveur peuvent subsister. Les sources sont dédupliquées et limitées à trois entrées affichées ; les réponses de repli peuvent ne comporter aucune source.

Si le widget n’apparaît pas après l’installation, consultez le Dépannage.

Pour des exemples propres à chaque plateforme, commencez par Docusaurus, MkDocs, VitePress, WordPress ou GitBook.

Masquer le widget sur certaines pages​

Pour masquer visuellement le widget uniquement sur certaines pages, appliquez ce CSS à ces pages seulement ; appliqué globalement, il masque le widget partout :

.chattybox-widget {
display: none;
}

Masquer le widget en CSS n’arrête ni son initialisation, ni ses requêtes API, ni ses rapports d’erreur ; ce n’est pas une mesure de consentement ou de confidentialité. Le loader ne décide pas lui-même du consentement : n’insérez le script qu’après le consentement requis, et empêchez sa réinsertion après un retrait du consentement ou sur une route exclue.

Pour les transitions de route côté client ou le retrait du consentement, le code source actuel du loader hébergé v16 fournit window.ChattyBox.destroy(). Le SDK npm 0.1.4 compte les handles de montage : appelez remove() pour chaque handle correspondant afin de déclencher le teardown final. Vérifiez que le loader effectivement déployé prend en charge ce teardown ; retirer uniquement la balise <script> ne suffit pas. Le teardown retire l’interface et les styles qu’il possède et annule le travail en attente, mais ne peut pas annuler une requête déjà traitée par le serveur.

Commandes du navigateur​

Dans le code source actuel du loader hébergé v16, window.ChattyBox existe pendant le démarrage avec status: 'loading' et destroy(). Après l’initialisation, vérifiez window.ChattyBox?.status === 'ready' avant d’appeler open(), close(), toggle() ou sendMessage(text). destroy() retire le widget et ses styles, annule son travail en cours et efface la variable globale ; il ne peut pas annuler les requêtes déjà traitées par le serveur. close() ferme uniquement le panneau et laisse le bouton d’ouverture en place. sendMessage(text) renvoie une promesse d’opération d’interface, pas une promesse contenant la réponse ; les envois effectués pendant le traitement d’un autre message sont ignorés. Cette variable globale est distincte des constructeurs SDK sur window.ChattyboxSDK. Vérifiez la version effectivement déployée avant de vous appuyer sur ce comportement.

Thèmes clair et sombre contrôlés par le site (code source actuel)​

Le workflow config-as-code du code source actuel prend en charge les palettes facultatives widget.theme.light et widget.theme.dark. Chacune accepte primaryColor, backgroundColor et textColor sous forme de couleurs hexadécimales à six chiffres ; les couleurs omises héritent de widget.theme. Les configurations à thème unique continuent de fonctionner sans changement. Cette fonctionnalité nécessite le CLI et le backend du code source actuel ainsi que le loader hébergé v16 ; le CLI/la configuration publiés en 0.3.1 n’acceptent pas encore ces champs. Ne supposez pas que le loader déployé est en v16.

Définissez data-theme="light" ou data-theme="dark" sur le script du loader avant son exécution pour choisir la palette initiale. Reliez ensuite le sélecteur du site à l’API du navigateur :

window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.

Le widget met à jour ses styles existants sans réinitialiser les messages, les sources, le brouillon ni une requête en attente. Le choix du thème ne peut ni activer/désactiver le widget ni retirer la mention de marque. Votre site gère l’enregistrement de la préférence et le thème du système d’exploitation ; le widget ne fait que sélectionner la palette configurée.

Intégrations personnalisées​

Vous avez besoin d’une configuration plus personnalisée que celle du widget hébergé ? Créez votre propre interface avec le SDK JavaScript ou contactez support@chattybox.ai pour obtenir de l’aide sur l’architecture.

Prise en charge multilingue​

Le widget du code source actuel résout la locale de l’interface selon le mode fixe ou automatique du projet. Le loader hébergé v16 observe les changements de <html lang> et de l’attribut data-locale du script et met à jour les libellés sans réinitialiser la conversation, le brouillon ni une tentative en attente. Un changement de route seul ne choisit pas de langue : mettez à jour l’un de ces attributs si nécessaire. Les changements de réglages dans le tableau de bord nécessitent toujours une nouvelle initialisation. Vérifiez la version effectivement déployée avant de vous appuyer sur ce comportement.

Langues officiellement prises en charge​

Le widget possède des catalogues pour 14 langues, tous de gauche à droite. Les catalogues localisent les libellés de l’interface appartenant au produit ; ils ne traduisent ni les textes rédigés par le projet ni les réponses générées par l’IA. Si la récupération des traductions échoue après le chargement réussi de la configuration, les libellés anglais intégrés restent utilisés.

LangueCode
Anglaisen
Françaisfr
Allemandde
Espagnoles
Italienit
Néerlandaisnl
Portugaispt
Polonaispl
Suédoissv
Indonésienid
Estonienet
Finnoisfi
Galloiscy
Tchèquecs

:::note Langue de l’UI et réponses Dans le code source actuel, le loader hébergé transmet la locale d’interface résolue avec les requêtes de chat. Le backend détecte la langue de la question et tente une récupération et une génération adaptées à cette langue. Un signal reconnu sur la langue de la question prime sur la locale de l’interface pour les messages de repli appartenant au produit ; si la détection n’est pas concluante ou repose uniquement sur l’heuristique d’anglais ASCII, la locale de l’interface peut déterminer leur langue. Un message de repli configuré par le projet est utilisé tel quel, et la locale ne traduit pas le contenu généré par l’IA. La qualité des réponses et les langues disponibles dépendent du contenu indexé et du modèle configuré. Vérifiez la version effectivement déployée avant de vous appuyer sur le comportement du loader v16. :::

Fonctionnement de la détection de langue​

Le widget utilise un système de détection en cascade :

  1. Remplacement autorisé – un data-locale pris en charge gagne seulement si allowLocaleOverride n’est pas faux, même en mode fixe.
  2. Mode fixe – sans remplacement autorisé pris en charge, le widget utilise defaultLocale et ignore la langue de la page et du navigateur.
  3. Mode automatique – il essaie <html lang>, navigator.language, chaque valeur de navigator.languages, l’ancienne propriété userLanguage, puis defaultLocale, en choisissant la première langue prise en charge.
  4. Normalisation – la casse est ignorée et les variantes régionales reconnues, telles que fr-CA, sont ramenées à leur langue de base prise en charge. Les valeurs non prises en charge sont ignorées ; si aucune ne convient, le widget utilise l’anglais. Les valeurs par défaut sont le mode automatique, l’anglais et les remplacements par script autorisés.

Les titres d’en-tête et les messages de bienvenue définis par le projet sont affichés tels quels, sans traduction automatique. Seuls les titres et messages par défaut prévus dans le code source actuel utilisent des libellés localisés. Si le chargement des traductions échoue, les libellés intégrés en anglais restent utilisés.

Remplacement manuel de la langue​

Pour demander une langue précise, activez d’abord Autoriser le remplacement par script, puis ajoutez data-locale avant le loader :

<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-locale="de"
data-api-url="https://adorable-woodpecker-629.convex.site/chat"
async
></script>

:::tip Cas d’utilisation C’est particulièrement utile si vous avez un site multilingue dont chaque version possède sa propre URL (par exemple, /de/, /fr/). Définissez data-locale selon la langue de chaque page et vérifiez l’interface rendue. :::

Réglages de langue du tableau de bord​

Le tableau de bord de l’application vous permet de configurer les préférences linguistiques du widget pour chaque projet :

  • Détection automatique – utilise la langue de la page avant celle du navigateur.
  • Fixe – utilise la langue par défaut configurée, sauf remplacement autorisé par script.
  • Autoriser le remplacement par script – permet ou non la surcharge par l’attribut data-locale.

Accédez à ces réglages dans votre tableau de bord → Projet → Personnaliser → Apparence → Langue. Vérifiez l’état d’enregistrement automatique et corrigez les erreurs avant de tester.

Correspondance de la langue du contenu​

Pour une expérience multilingue utile, indexez du contenu public dans les langues de vos visiteurs et testez les sources : la détection et la récupération ne sont pas garanties. Pour cela :

  1. Scrapez toutes les versions linguistiques de votre documentation à l’aide du fichier sitemap.xml.
  2. Le scraper tente de détecter la langue : inspectez les contenus et citations au lieu de supposer un résultat exact.
  3. La récupération tente de préférer la langue détectée de la question, mais peut revenir à un autre contenu indexé.

Configuration dans le tableau de bord de l’application : lors de la configuration du scraping, utilisez l’URL de votre sitemap.xml (par exemple, https://yourdocs.com/sitemap.xml) pour découvrir des versions linguistiques, puis vérifiez les pages indexées. Les sitemaps ne contournent pas les limites de crawl ni les exclusions.

Dépannage​

Le widget s’affiche toujours en anglais​

  • Actualisation forcée à titre de diagnostic – Rechargez la page avec Ctrl+F5 ou Cmd+Shift+R, puis consultez les requêtes du widget et des traductions dans le panneau réseau du navigateur.
  • Vérifiez data-locale – Assurez-vous que l’attribut est correctement défini avec un code de langue pris en charge.
  • Vérifiez le mode et l’autorisation – Un mode fixe ou les remplacements désactivés peuvent volontairement ignorer data-locale ou le navigateur.
  • Vérifiez la langue du navigateur – Contrôlez la langue préférée configurée dans votre navigateur.
  • Vérifiez le lang du HTML de la page – Assurez-vous que votre page contient <html lang="de"> (ou le code approprié).

Les sources sont dans la mauvaise langue​

  • Re-scrapez votre contenu – Vérifiez que les versions linguistiques voulues sont indexées.
  • Utilisez sitemap.xml – Vérifiez que les URL voulues ont réellement été indexées : limites et exclusions peuvent les omettre.
  • Vérifiez la langue de la requête – L’IA tente d’adapter la langue de la réponse à celle de la requête.

Des traductions manquent​

  • Vérifiez les langues et les requêtes prises en charge – Seuls les 14 codes répertoriés ci-dessus ont des catalogues. Si la récupération du catalogue échoue après celle de la configuration, les libellés anglais intégrés sont utilisés ; si la récupération de la configuration échoue, le widget reste indisponible.

Bonnes pratiques​

  1. Définissez <html lang> sur vos pages – Cela aide à l’accessibilité et à la détection du widget.
  2. Testez avec data-locale pendant le développement – Vérifiez que chaque langue s’affiche correctement.
  3. Scrapez toutes les versions linguistiques – Utilisez sitemap.xml pour les découvrir et vérifiez les pages indexées.
  4. Examinez les vraies questions – Consultez les conversations pour repérer les lacunes de contenu propres à chaque langue ; le tableau de bord n’offre pas de rapport de répartition des locales du widget.