Guide all'installazione

:::note Stato delle versioni L’SDK npm pubblicato 0.1.4 con widget.js v15 supporta il teardown con remove() o window.ChattyBox.destroy() e annulla il lavoro in attesa. :::

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. Per impostazione predefinita funziona in produzione, nelle anteprime e nello staging e su localhost. Per aggiungere un ulteriore livello facoltativo di protezione, scegli Edit origins, abilita Restrict this key to specific origins e aggiungi le origini consentite esatte. Quando è abilitata, la corrispondenza include schema, hostname e porta: https://example.com, https://preview.example.com e http://localhost:3000 sono voci separate. Torna in Embed, seleziona la chiave 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:

Attributo	Obbligatorio	Utilizzo
`src`	Sì	Carica il JavaScript del widget ChattyBox.
`data-api-key`	Sì	Identifica la chiave pubblica del widget per il progetto.
`data-api-url`	Sì	Invia le richieste del widget all'API ChattyBox.
`data-locale`	No	Richiede lingua all’avvio, solo con override consentiti.
`data-chattybox-widget="true"`	No	Permette a SDK/loader dinamici di trovare lo script.

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 delle restrizioni facoltative sulle origini per chiave. Apri Public Keys > Edit origins per abilitare una restrizione e aggiungere o rimuovere origini di produzione, staging, anteprima o localhost.
Scraping, nuovo scraping, chat di test, Analytics e lacune informative.

Se abiliti il blocco della configurazione come codice, l'assistente, la fonte, il runtime e le impostazioni supportate del widget provengono dalla configurazione distribuita invece che dai moduli della dashboard. Le chiavi pubbliche e le restrizioni opzionali sulle origini restano impostazioni 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 SPA React, aggiungi lo script una volta nell’app shell. Nell’SDK pubblicato 0.1.4, mount identici condividono lo script; chiama remove() per ogni handle e solo l’ultimo segnala a widget.js v15 di rimuovere UI, stili, link ai font, lavoro in attesa, script e API globale. Opzioni diverse vengono rifiutate finché esistono handle.

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.

Apri il contenitore GTM.
Crea un nuovo tag Custom HTML.
Incolla lo snippet ChattyBox.
Usa un trigger All Pages oppure un trigger più ristretto solo per le pagine in cui deve comparire il widget.
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.

Guida al plugin WordPress

Per un'installazione WordPress senza codice, usa il plugin WordPress ChattyBox. Segui la guida al plugin WordPress per installarlo, configurarlo, escludere route e verificarlo. L'endpoint API di produzione viene configurato automaticamente.

Il plugin carica il widget ospitato nelle richieste del frontend pubblico senza modificare il tema. Non viene caricato intenzionalmente in wp-admin, nei feed o nelle richieste REST o AJAX.

Se preferisci installare manualmente lo script, usa una delle posizioni per gli script già supportate dalla tua configurazione WordPress:

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

Colloca lo snippet in una posizione globale del footer affinché compaia nelle pagine pubblicate, negli articoli, nei documenti e negli articoli della knowledge base in cui deve essere disponibile il chatbot.

<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. Controlla le origini solo se hai esplicitamente abilitato una restrizione per la chiave.

Prima dell'installazione​

Cosa deve contenere lo script​

HTML semplice​

Next.js / App shell React​

Docusaurus​

Interfaccia personalizzata​

CMS generico/HTML personalizzato​

Google Tag Manager​

Guida al plugin WordPress​

Modulo Drupal​

Verifica​

Preferenze sulla privacy