Guides d’installation

:::note État des versions Le SDK npm publié 0.1.4 permet de retirer ses montages avec remove(). Après l’initialisation du widget hébergé widget.js v15, window.ChattyBox.destroy() permet aussi de le détruire. :::

L’intégration hébergée widget.js est la solution sans build si vous souhaitez que ChattyBox gère l’interface et le transport. Si votre application doit initialiser la même interface depuis du code npm, utilisez mountWidget(). Pour gérer vous-même l’interface, utilisez le SDK headless.

Avant l’installation

Suivez d’abord le parcours Prise en main : configurez et importez la source, vérifiez les pages indexées et validez des réponses représentatives dans Tester le chatbot.

Dans Installer, préparez une installation pour votre site web ou gérez une clé compatible avec le navigateur dans Clés et domaines. Vérifiez les origines de la clé : une clé préparée pour un domaine de site web peut déjà être restreinte à cette origine, tandis qu’une clé créée sans restriction fonctionne sur plusieurs origines. Dans Modifier les origines, vous pouvez activer une restriction facultative et ajouter les origines de production, de prévisualisation, de staging et de localhost nécessaires. Lorsqu’elles sont activées, les origines sont comparées exactement selon le schéma, le nom d’hôte et le port : https://example.com, https://preview.example.com et http://localhost:3000 sont distincts. Dans Installation sur le site web, sélectionnez la clé et copiez le snippet généré, qui contient la clé publique et l’URL de l’API de votre projet :

Saisissez d’abord une URL de site web HTTP(S). Le sélecteur ne propose que les clés non expirées sans restriction ou autorisées pour l’origine de cette URL. Pour sélectionner une clé restreinte, saisissez une origine autorisée ; utilisez Gérer les clés et les domaines autorisés pour examiner ses restrictions. Si le formulaire est indisponible, terminez d’abord l’étape de configuration indiquée dans le tableau de bord.

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

Pour les plateformes orientées documentation, consultez les guides chatbot IA pour MkDocs, chatbot IA pour VitePress et chatbot IA pour GitBook.

Remplacez YOUR_API_KEY par la clé publique du widget fournie par votre tableau de bord. Conservez la valeur de data-api-url exactement telle qu’elle apparaît dans le tableau de bord. En production, il s’agit d’une URL stable https://...convex.site/chat pour l’API publique du widget.

Ce qui doit figurer dans le script

Utilisez les attributs du script pour les valeurs qui doivent être disponibles avant le démarrage du widget :

Attribut	Obligatoire	Utilisation
src	Oui	Charger le JavaScript du widget ChattyBox.
data-api-key	Oui	Identifier la clé publique du widget de votre projet.
data-api-url	Oui	Envoyer les requêtes du widget à l’API ChattyBox.
data-locale	Non	Demander une langue d’interface à l’initialisation, seulement si le projet autorise le remplacement par script.
data-chattybox-widget="true"	Non	Permettre aux chargeurs dynamiques et au SDK de trouver un script existant ; recommandé pour une injection depuis le code de l’application.
data-debug="true"	Non	Activer les diagnostics du navigateur ; désactivés par défaut.
data-color	Non	Remplacer explicitement la couleur d’accent après le chargement réussi de la configuration ; utiliser une couleur hexadécimale à six chiffres. Le dashboard est préférable.
data-position	Non	Remplacer explicitement la position après le chargement réussi de la configuration : bottom-right, bottom-left, top-right ou top-left. Le dashboard est préférable.

Utilisez les réglages du tableau de bord pour tout ce qui doit être géré sans redéployer votre site :

• Couleurs, position, icône, titre et message de bienvenue du widget.
• Mode de langue par défaut et autorisation des remplacements data-locale.
• Création et suppression des clés publiques et restrictions d’origine facultatives par clé. Dans Clés et domaines > Modifier les origines, activez une restriction et ajoutez ou retirez les origines de production, de staging, de prévisualisation ou de localhost.
• Import et actualisation du contenu, tests du chatbot, analyses et questions sans réponse.

Si vous activez le verrouillage de la configuration comme du code, l’assistant, la source, l’environnement d’exécution et les réglages pris en charge du widget proviennent de la configuration déployée, et non des formulaires du dashboard. Le verrouillage est irréversible et bloque aussi les opérations manuelles de contenu. Les clés publiques et leurs restrictions d’origine facultatives restent des paramètres de configuration du projet, pas des valeurs du fichier de configuration.

L’URL de l’API peut être la racine du déploiement HTTP ou se terminer par /chat ; le chargeur retire les barres obliques finales et un /chat final avant de dériver ses points de terminaison. Il ne convertit pas une URL Convex en .cloud vers .site. N’ajoutez ni chaîne de requête ni fragment à cette valeur.

Le SDK reconnaît l’attribut marqueur ci-dessus, et pas nécessairement tous les scripts manuels qui partagent le même src. N’installez qu’un seul chargeur. Le SDK npm publié 0.1.4 ne partage une balise qu’entre montages aux options identiques et rejette une clé, un point de terminaison, une URL de script, une locale ou un réglage de diagnostic modifié tant que des handles subsistent. Le widget hébergé ne suit pas les changements de configuration du dashboard : réinitialisez-le pour prendre en compte les réglages enregistrés. Dans le code source actuel du widget hébergé widget.js v16, les libellés de l’interface appartenant au produit peuvent s’actualiser lorsque <html lang> ou data-locale modifie la locale résolue, selon la politique de locale du projet. Vérifiez la version du chargeur déployé avant de vous fier aux mises à jour côté client ; ce comportement du chargeur hébergé ne décrit pas le SDK npm 0.1.4. Les restrictions d’origine, si elles sont activées, utilisent Origin ou l’origine de repli de Referer ; une origine absente ou non autorisée renvoie 401 Invalid API key. Ce n’est pas une authentification.

HTML simple

Collez le snippet une seule fois vers la fin de body, juste avant </body>. Cette méthode fonctionne pour le HTML statique, les sites codés manuellement et les modèles qui exposent un pied de page global.

<!doctype html>
<html lang="en">
  <head>
    <title>Example Site</title>
  </head>
  <body>
    <main>
      <!-- Page content -->
    </main>

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

Next.js / shell d’application React

Pour un site Next.js avec App Router, ajoutez le widget dans app/layout.tsx avec next/script afin qu’il soit chargé une seule fois pour toute l’application.

import Script from "next/script";
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://chattybox.ai/widget.js"
          data-api-key="YOUR_API_KEY"
          data-api-url="YOUR_WIDGET_API_URL"
          data-chattybox-widget="true"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Dans une application monopage React, ajoutez le script une seule fois dans la shell d’application de niveau supérieur ou dans le modèle HTML. Ne l’injectez pas depuis chaque composant de route.

Conservez le chargeur dans une shell persistante lors de la navigation normale. Pour le démontage ou le retrait du consentement, consultez les précautions de nettoyage après l’exemple Docusaurus ci-dessous ; retirer une balise seule ne garantit pas ce nettoyage.

import { useEffect } from "react";

export function ChattyBoxWidget() {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return null;
}

Docusaurus

Avec Docusaurus, créez ou mettez à jour src/theme/Root.tsx afin que le widget soit disponible sur toutes les pages de documentation.

import React, { useEffect } from "react";

export default function Root({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return <>{children}</>;
}

Si votre site Docusaurus possède des routes traduites, définissez data-locale avant le chargement seulement si les remplacements sont autorisés, ou utilisez le mode automatique avec <html lang>. Le mode fixe utilise la locale par défaut du projet, sauf remplacement autorisé. Dans le code source actuel du widget hébergé widget.js v16, les libellés du produit peuvent s’actualiser si <html lang> ou data-locale change la locale résolue, selon la politique du projet. Vérifiez le comportement de la version déployée avant de compter sur ces mises à jour ; cela ne concerne pas le SDK npm publié 0.1.4. Le titre et le message d’accueil rédigés par le client, ainsi que les réponses générées, ne sont pas traduits automatiquement.

Conservez le chargeur dans la shell persistante lors des changements de route normaux. Pour un démontage intentionnel ou une révocation du consentement, retirez tous les handles du SDK 0.1.4 : le dernier handle correspondant signale au widget hébergé widget.js v15 de détruire son interface et ses styles, et d’annuler l’initialisation, les nouvelles tentatives (jusqu’à 10 essais en 30 secondes) ainsi que le chat en cours. Après l’initialisation de v15, window.ChattyBox.destroy() est également disponible. Le nettoyage ne peut pas annuler une requête déjà traitée par le serveur. Le widget hébergé est ajouté à document.body ; il ne s’affiche pas dans le composant qui charge le script.

Interface personnalisée

Le widget hébergé est facultatif. Si vous souhaitez un contrôle total du rendu, de l’état des messages et de la conception des interactions, utilisez le SDK JavaScript avec la même clé API publique du widget et la même URL d’API du widget.

CMS générique/HTML personnalisé

La plupart des plateformes CMS disposent d’une zone de code personnalisé globale, d’un pied de page ou d’un modèle de thème. Ajoutez-y le script afin que chaque page publique puisse charger le widget.

Utilisez cette solution pour Webflow, Framer, Squarespace, les zones de code personnalisé Wix, les thèmes Shopify, les modèles HubSpot et les plateformes CMS personnalisées qui permettent de modifier le HTML global.

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

Avant de publier, vérifiez que le CMS ne supprime pas data-api-key, data-api-url ou async des scripts personnalisés.

Google Tag Manager

Utilisez Google Tag Manager si votre équipe gère déjà les scripts tiers avec GTM.

1. Ouvrez votre conteneur GTM.
2. Créez une nouvelle balise Custom HTML.
3. Collez le snippet ChattyBox.
4. Utilisez un déclencheur All Pages, ou un déclencheur plus restreint pour les seules pages qui doivent afficher le widget.
5. Prévisualisez le conteneur, vérifiez que le widget se charge, puis publiez.

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

Si votre site utilise le mode de consentement ou une politique de consentement des balises, assurez-vous que le widget peut se charger sur les pages où les visiteurs ont besoin d’aide.

Dans une SPA, un déclencheur GTM plus ciblé évite le chargement initial sur les routes exclues, mais ne retire pas un widget déjà chargé sur une autre route. Ne déclenchez pas de nouveau le chargeur à chaque changement d’historique.

Sécurité du contenu et politique CSP

Pour le chargeur hébergé par défaut, autorisez https://chattybox.ai dans script-src et l’origine de l’API du widget dans connect-src. Le widget injecte une feuille de style et des attributs de style en ligne ; il ne propose actuellement pas d’option de nonce. Une politique qui interdit les styles en ligne bloquera donc une partie de l’interface. Si votre politique le permet, autorisez 'unsafe-inline' pour ces styles ou utilisez une interface personnalisée compatible avec votre politique. Le chargement d’Inter à l’ouverture du launcher nécessite aussi https://fonts.googleapis.com dans style-src et https://fonts.gstatic.com dans font-src. Autorisez dans img-src l’origine de toute icône configurée. Vérifiez les exigences de consentement et de sécurité avant d’assouplir la CSP.

Guide du plugin WordPress

Pour une installation WordPress sans code, utilisez le plugin WordPress ChattyBox. Suivez le guide du plugin WordPress pour l’installer, le configurer, exclure des routes et le vérifier. Le point de terminaison de production est configuré automatiquement.

Le plugin charge le widget hébergé lors des requêtes frontend publiques sans modifier votre thème. Il ne se charge intentionnellement pas dans wp-admin, les flux, les requêtes REST ou les requêtes AJAX. Ce comportement ne constitue pas un contrôle d’accès ou de confidentialité pour chaque page frontend : si nécessaire, configurez et testez les exclusions des pages de paiement, de compte, protégées par mot de passe ou réservées aux membres à l’aide du filtre du plugin, ou utilisez une installation manuelle limitée aux pages voulues. Le réglage de l’URL du chargeur du plugin ne modifie pas son point de terminaison de production intégré ; pour une autre API, utilisez le snippet manuel.

Pour un repli manuel, placez le snippet dans un pied de page global avec l’une de ces options :

• Les réglages du thème qui fournissent des scripts d’en-tête ou de pied de page.
• Un thème enfant qui contrôle le modèle de pied de page.
• Un plugin de scripts d’en-tête/pied de page.
• Google Tag Manager si votre site WordPress l’utilise déjà.

Collez le snippet dans un emplacement de pied de page global afin qu’il apparaisse sur les pages, articles, documents et articles de base de connaissances publiés où le chatbot doit être disponible.

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

Évitez d’ajouter le widget aux pages wp-admin, de paiement, de compte ou d’espace membre privé, sauf si ces pages sont volontairement publiques et prises en charge.

Module Drupal

Pour Drupal 10 ou 11, Composer est la méthode d’installation recommandée. Ajoutez le dépôt VCS GitHub public au composer.json racine du projet Drupal qui le consomme :

{
  "repositories": {
    "chattybox-drupal": {
      "type": "vcs",
      "url": "https://github.com/OpenStaticFish/chattybox-drupal.git"
    }
  }
}

Installez ensuite le module balisé et activez-le :

composer require openstaticfish/chattybox-drupal:^0.1
drush en chattybox

Ouvrez Configuration > Web services > ChattyBox, collez la clé API publique du widget préparée dans Installer → Installation sur le site web et activez le chatbot. La version du module auditée localement utilise un point de terminaison API codé en dur : comparez-le à celui de votre snippet et utilisez l’intégration manuelle pour un autre déploiement d’API. Le module est désactivé par défaut. Il ignore les requêtes administratives et non HTML, mais pas tout contenu frontend privé. Modifier l’URL du script ne change pas le point de terminaison de production intégré. Consultez le guide du module chatbot Drupal pour les exclusions de routes et la solution manuelle.

Vérification

Après l’installation, suivez la checklist de lancement avant d’annoncer le chatbot :

• Ouvrez une page publique dans une fenêtre de navigation privée.
• Vérifiez que le launcher du widget apparaît.
• Ouvrez le widget et posez une vraie question de client.
• Vérifiez qu’une réponse prise en charge comporte des citations de sources, puis posez une question dont la réponse ne figure pas dans le contenu et vérifiez le repli (qui peut ne citer aucune source).
• Consultez la console du navigateur pour détecter l’absence de data-api-key, l’absence de data-api-url ou des erreurs de clé. Vérifiez si des restrictions d’origine sont activées pour la clé et, le cas échéant, si l’origine souhaitée est autorisée.