:::note État des versions Le SDK npm publié 0.1.4 avec widget.js v15 prend en charge le teardown par remove() ou window.ChattyBox.destroy() : il supprime UI/styles et annule initialisation, tentatives et chats en cours. Le chat v15 effectue au plus 10 tentatives dans un budget de planification de 30 s, pas un délai strict par requête. sendMessage() headless ne réessaie pas automatiquement. :::

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 Test Chat 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 l’onglet Embed.
3. Prévisualisez et enregistrez l’apparence et le comportement linguistique du widget.

L’onglet Embed contrôle la présentation et génère le code d’installation, mais les clés publiques sont gérées séparément. Lorsque vous êtes prêt à installer le widget :

1. Ouvrez Public Keys et créez une clé de navigateur.
2. Par défaut, la clé fonctionne sur production, prévisualisation, staging et localhost. Pour une protection facultative, ouvrez Edit origins, activez la restriction et ajoutez les origines exactes autorisées.
3. Revenez dans Embed, sélectionnez la clé et copiez le snippet généré.
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 ; les pages déjà ouvertes doivent être rechargées. 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. Accent Color – Choisissez la couleur principale de votre marque. Elle s’applique au launcher, aux éléments mis en évidence et aux messages des utilisateurs.

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

3. Header Title – Définissez le titre affiché en haut de la fenêtre de chat.

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

L’éditeur fournit aussi arrière-plan, couleur du texte et icône (robot, emoji, URL ou image téléversée). Les icônes téléversées sont limitées à 512 KiB et à PNG, JPEG, WebP, SVG, GIF ou ICO. La taille enregistrée de l’icône n’est pas encore lue par le loader : elle ne la redimensionne pas.

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.

Les restrictions d’origine sont facultatives : elles correspondent exactement au schéma, hôte et port, et constituent une protection en profondeur, pas une authentification.

Utilisez les attributs du script uniquement pour les valeurs dont le widget a besoin au chargement de la page :

• 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 à l’initialisation seulement si le projet l’autorise.
• data-color et data-position remplacent respectivement la couleur et position enregistrées après configuration ; préférez le tableau de bord.
• data-debug="true" active les diagnostics de console.

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 sur certaines pages, vous pouvez utiliser CSS :

.chattybox-widget {
  display: none;
}

Masquer en CSS n’arrête ni l’initialisation, ni les requêtes API, ni les rapports d’erreur ; ce n’est pas une mesure de consentement. Pour empêcher le chargement, excluez le script sur ces requêtes. Pour une transition de route ou une révocation du consentement, le widget hébergé v15 fournit window.ChattyBox.destroy() et le SDK publié 0.1.4 utilise remove() pour le même teardown.

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 résout sa locale d’interface à l’initialisation selon le mode du projet ; il ne surveille pas les attributs ni les changements de route côté client.

Langues officiellement prises en charge

Le widget possède des catalogues pour 14 langues, tous de gauche à droite. La présence d’un catalogue ne garantit ni que chaque libellé est traduit, ni la qualité des réponses : certaines étiquettes restent aujourd’hui en anglais.

Langue	Code
Anglais	en
Français	fr
Allemand	de
Espagnol	es
Italien	it
Néerlandais	nl
Portugais	pt
Polonais	pl
Suédois	sv
Indonésien	id
Estonien	et
Finnois	fi
Gallois	cy
Tchèque	cs

:::note Langue de l’UI et réponses La locale d’interface n’est pas envoyée comme paramètre de langue du chat. Le backend détecte la langue de la question et tente une récupération adaptée ; qualité et langues de réponse dépendent du contenu indexé et du modèle. :::

Fonctionnement de la détection de langue

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

1. Remplacement autorisé – un data-locale non vide gagne seulement si allowLocaleOverride n’est pas faux, même en mode fixe.
2. Mode fixe – sans remplacement autorisé, le widget utilise defaultLocale.
3. Mode automatique – il essaie <html lang>, puis la langue du navigateur, puis defaultLocale.
4. Normalisation – fr-CA peut devenir fr, mais une valeur non prise en charge devient immédiatement l’anglais sans essayer le candidat suivant.

Remplacement manuel de la langue

Pour demander une langue précise, activez d’abord Allow Script Override, 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 :

• Auto-detect – utilise la langue de la page avant celle du navigateur.
• Fixed Language – utilise la langue configurée, sauf remplacement autorisé.
• Allow Script Override – Active ou désactive la surcharge via l’attribut data-locale.

Accédez à ces réglages dans votre tableau de bord → Projet → onglet Embed → section Widget Language.

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 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 prises en charge – Seuls les 14 codes répertoriés ci-dessus ont des catalogues ; des libellés manquants peuvent utiliser le repli anglais.

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 – Le tableau de bord n’offre pas de rapport de répartition des locales du widget.