Guides d’installation

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 scrapez la source, vérifiez les pages indexées et validez des réponses représentatives dans Test Chat.

Créez ensuite une clé compatible avec le navigateur dans Public Keys et limitez ses origines autorisées. Revenez dans Embed, sélectionnez cette clé, terminez la personnalisation du widget hébergé et copiez le snippet généré. Il contient la clé publique et l’URL de l’API de votre projet :

<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	Forcer la langue de l’interface du widget sur une page donnée.

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, ainsi que toutes les restrictions d’origine autorisées configurées pour votre projet.
Scraping, re-scraping, chat de test, Analytics et lacunes de contenu.

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 plutôt que des formulaires du tableau de bord. Les clés publiques et les origines autorisées restent des identifiants de configuration du projet, et non des valeurs du fichier de configuration.

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"
          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.

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 à partir de la langue de la page actuelle ou utilisez la valeur <html lang> de la page.

Conservez le loader dans la shell d’application persistante. Ne le recréez pas et ne le supprimez pas lors des changements de route client normaux.

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.

Ouvrez votre conteneur GTM.
Créez une nouvelle balise Custom HTML.
Collez le snippet ChattyBox.
Utilisez un déclencheur All Pages, ou un déclencheur plus restreint pour les seules pages qui doivent afficher le widget.
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.

WordPress

ChattyBox ne nécessite pas de plugin WordPress. Utilisez l’un des emplacements de script déjà pris en charge par votre installation WordPress :

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.

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 que la réponse contient des citations de sources.
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é/origine.

Avant l’installation​

Ce qui doit figurer dans le script​

HTML simple​

Next.js / shell d’application React​

Docusaurus​

Interface personnalisée​

CMS générique/HTML personnalisé​

Google Tag Manager​

WordPress​

Vérification​

Privacy choices