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:
| 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 | Forza 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.
- 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.
WordPress
ChattyBox non richiede un plugin WordPress. Usa una delle posizioni per gli script già supportate dalla 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à.
Incolla lo snippet in una posizione globale del footer, così apparirà nelle pagine, nei post, nei documenti e negli articoli della knowledge base pubblicati in cui il chatbot deve essere disponibile.
<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.
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 didata-api-urlo eventuali errori di chiave/origine.