Passa al contenuto principale
ChattyBox Logo

Guide all'installazione

L'integrazione ospitata widget.js è la soluzione senza build quando vuoi che ChattyBox gestisca interfaccia e trasporto. Se l'app deve inizializzare la stessa UI dal codice npm, usa mountWidget(). Per gestire direttamente la UI, usa l'SDK headless.

Prima dell'installazione​

Completa prima il flusso Per iniziare: configura ed esegui lo scraping della fonte, verifica le pagine indicizzate e valida risposte rappresentative in Test Chat.

Poi crea una chiave sicura per il browser in Public Keys e limita le origini consentite. Torna in Embed, seleziona la chiave, completa la personalizzazione del widget ospitato e copia lo snippet generato. Contiene la chiave pubblica e l'URL API del progetto:

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

Per le piattaforme orientate alla documentazione, consulta le guide chatbot AI per MkDocs, chatbot AI per VitePress e chatbot AI per GitBook.

Sostituisci YOUR_API_KEY con la chiave pubblica del widget della dashboard. Mantieni il valore data-api-url esattamente come appare nella dashboard. In produzione è un URL stabile https://...convex.site/chat per l'API pubblica del widget.

Cosa deve contenere lo script​

Usa gli attributi dello script per i valori che devono essere disponibili prima dell'avvio del widget:

AttributoObbligatorioUtilizzo
srcSìCarica il JavaScript del widget ChattyBox.
data-api-keySìIdentifica la chiave pubblica del widget per il progetto.
data-api-urlSìInvia le richieste del widget all'API ChattyBox.
data-localeNoForza la lingua della UI del widget in una pagina specifica.

Usa le impostazioni della dashboard per tutto ciò che deve essere gestito senza ridistribuire il sito:

  • Colori, posizione, icona, titolo e messaggio di benvenuto del widget.
  • Modalità lingua predefinita e autorizzazione degli override data-locale.
  • Creazione ed eliminazione delle chiavi pubbliche e qualsiasi restrizione sulle origini consentite configurata per il progetto.
  • Scraping, nuovo scraping, chat di test, Analytics e lacune informative.

Se abiliti il blocco della configurazione come codice, assistente, fonte, runtime e impostazioni supportate del widget provengono dalla configurazione distribuita invece che dai moduli della dashboard. Le chiavi pubbliche e le origini consentite restano credenziali di configurazione del progetto, non valori del file di configurazione.

HTML semplice​

Incolla lo snippet una volta vicino alla fine di body, subito prima di </body>. Funziona con HTML statico, siti scritti a mano e template che espongono un footer globale.

<!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 / App shell React​

Per un sito Next.js con App Router, aggiungi il widget a app/layout.tsx con next/script in modo che venga caricato una volta per tutta l'app.

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>
  );
}

Per una single-page app React, aggiungi lo script una volta nell'app shell di livello superiore o nel template HTML. Non inserirlo da ogni componente di 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​

In Docusaurus, crea o aggiorna src/theme/Root.tsx così il widget sarà disponibile in tutte le pagine della documentazione.

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}</>;
}

Se il sito Docusaurus ha route tradotte, imposta data-locale in base alla lingua della pagina corrente oppure affidati al valore <html lang> della pagina.

Mantieni il loader nell'app shell persistente. Non ricrearlo né rimuoverlo durante i normali cambi di route lato client.

Interfaccia personalizzata​

Il widget ospitato è facoltativo. Se vuoi il pieno controllo del rendering, dello stato dei messaggi e del design delle interazioni, usa l'SDK JavaScript con la stessa chiave API pubblica e lo stesso URL API del widget.

CMS generico/HTML personalizzato​

La maggior parte delle piattaforme CMS dispone di un'area globale per il codice personalizzato, un footer o un template del tema. Aggiungi lì lo script, così ogni pagina pubblica potrà caricare il widget.

Usa questo percorso per Webflow, Framer, Squarespace, le aree di codice personalizzato di Wix, i temi Shopify, i template HubSpot e le piattaforme CMS personalizzate che consentono di modificare l'HTML globale.

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

Prima di pubblicare, verifica che il CMS non rimuova data-api-key, data-api-url o async dagli script personalizzati.

Google Tag Manager​

Usa Google Tag Manager quando il team gestisce già gli script di terze parti tramite GTM.

  1. Apri il contenitore GTM.
  2. Crea un nuovo tag Custom HTML.
  3. Incolla lo snippet ChattyBox.
  4. Usa un trigger All Pages oppure un trigger più ristretto solo per le pagine in cui deve comparire il widget.
  5. Visualizza il contenitore in anteprima, verifica che il widget venga caricato e poi pubblica.
<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Se il sito usa la modalità consenso o una policy di consenso dei tag, assicurati che il widget possa essere caricato nelle pagine in cui i visitatori hanno bisogno di aiuto.

WordPress​

Per i passaggi dettagliati relativi all'installazione e alla configurazione del plugin, all'esclusione delle route e alla verifica, consulta la guida al plugin WordPress.

Per la maggior parte dei siti WordPress, installa e attiva il plugin WordPress ufficiale di ChattyBox:

  1. Nell’amministrazione WordPress, installa e attiva il plugin ChattyBox AI Chatbot.
  2. Apri Impostazioni > ChattyBox.
  3. Incolla solo la chiave API pubblica del widget dalla scheda Embed. L’endpoint API di produzione viene configurato automaticamente.
  4. Abilita il chatbot e verificalo su una pagina pubblica.

Come fallback manuale, inserisci lo snippet in una posizione globale del footer usando una di queste opzioni:

  • Impostazioni del tema che forniscono script per header o footer.
  • Un tema child che controlla il template del footer.
  • Un plugin per script di header/footer.
  • Google Tag Manager se il sito WordPress lo utilizza già.
<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Evita di aggiungere il widget alle pagine wp-admin, checkout, account o membership private, a meno che tali pagine non siano intenzionalmente pubbliche e supportate.

Modulo Drupal​

Per Drupal 10 o 11, Composer è il percorso di installazione consigliato. Aggiungi il repository VCS GitHub pubblico al composer.json principale del progetto Drupal che lo utilizza:

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

Poi installa il modulo contrassegnato e abilitalo:

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

Apri Configuration > Web services > ChattyBox, incolla la chiave API pubblica del widget dalla scheda Embed del progetto e abilita il chatbot. L'endpoint API di produzione viene configurato automaticamente. Consulta la guida al modulo chatbot Drupal per escludere le route e per l'alternativa manuale.

Verifica​

Dopo l'installazione, completa la checklist di lancio prima di annunciare il chatbot:

  • Apri una pagina pubblica in una finestra in incognito.
  • Conferma che compaia il launcher del widget.
  • Apri il widget e poni una domanda reale di un cliente.
  • Verifica che la risposta includa citazioni delle fonti.
  • Controlla nella console del browser l'assenza di data-api-key, l'assenza di data-api-url o eventuali errori di chiave/origine.

Privacy choices

We use optional analytics and tag-management tools to understand site use. Choose whether to allow PostHog and Google Tag Manager. Turning analytics off reloads this page so the change takes effect cleanly. Essential site functionality and error monitoring are not controlled by this choice. Read our privacy policy.