:::note Stato delle versioni L’SDK npm pubblicato 0.1.4 con widget.js v15 supporta il teardown tramite remove() o window.ChattyBox.destroy(): rimuove UI/stili e annulla inizializzazione, retry e chat in corso. Il chat v15 esegue al massimo 10 tentativi nel budget di pianificazione di 30 s, non un timeout rigido per richiesta. sendMessage() headless non ritenta automaticamente. :::

Personalizzazione del widget ospitato

Personalizza l'interfaccia pronta all'uso caricata da https://chattybox.ai/widget.js. Per gli esempi canonici di installazione per framework e piattaforma, consulta le Guide all'installazione.

Prima di personalizzare

Crea il progetto, indicizzane i contenuti e verifica risposte rappresentative in Test Chat prima di dedicare tempo alla presentazione. Consulta Per iniziare per la sequenza completa.

Configura il widget ospitato

1. Vai alla tua dashboard e seleziona il progetto.
2. Apri la scheda Embed.
3. Visualizza in anteprima e salva l'aspetto e il comportamento linguistico del widget.

La scheda Embed controlla la presentazione e genera il codice di installazione, ma le chiavi pubbliche vengono gestite separatamente. Quando sei pronto per installare:

1. Apri Public Keys e crea una chiave browser.
2. Limita le origini consentite ai domini del sito previsti.
3. Torna in Embed, seleziona la chiave e copia lo snippet generato.
4. Segui le Guide all'installazione per la tua piattaforma.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

mancia

Le modifiche salvate vengono applicate alla prossima inizializzazione: ricarica la pagina; quelle già aperte non cambiano in tempo reale.

---

Personalizzazione visiva

ChattyBox include un editor visivo completamente integrato. Puoi modificare l'aspetto del widget per adattarlo perfettamente al tuo brand senza toccare il codice.

Controlli della dashboard

1. Accent Color – Scegli il colore principale del brand. Influisce sul launcher, sulle evidenziazioni principali e sui messaggi degli utenti.

2. Position – Scegli dove deve comparire il widget sullo schermo.

3. Header Title – Imposta il titolo mostrato in cima alla finestra della chat.

4. Welcome Message – Personalizza il primo messaggio che i visitatori vedono quando aprono la chat.

nota

Le modifiche apportate nella dashboard vengono applicate immediatamente. Non è necessario aggiornare il codice embed sul sito.

Opzioni avanzate

Impostazioni della dashboard e attributi dello script

La maggior parte del comportamento del widget dovrebbe essere gestita dalla dashboard, così non dovrai ridistribuire il sito per le modifiche semplici.

Usa la dashboard per colori, posizione, icona, titolo dell'intestazione, messaggio di benvenuto, lingue predefinite, gestione delle chiavi pubbliche, scraping e Analytics.

Se il progetto usa restrizioni sulle origini delle chiavi pubbliche, mantienile sincronizzate con i domini su cui il widget è installato.

Usa gli attributi dello script solo per i valori necessari al widget al caricamento della pagina:

• data-api-key identifica la chiave pubblica del widget.
• data-api-url indica al widget dove inviare le richieste. In produzione è un URL stabile https://...convex.site/chat presente nella dashboard.
• data-locale richiede una lingua all’inizializzazione solo se il progetto consente gli override dello script.

Se il widget non compare dopo l'installazione, consulta la Risoluzione dei problemi.

Per esempi specifici per piattaforma, inizia da Docusaurus, MkDocs, VitePress, WordPress o GitBook.

Nascondi il widget in pagine specifiche

Se devi nascondere il widget in alcune pagine, puoi farlo con CSS:

.chattybox-widget {
  display: none;
}

Integrazioni personalizzate

Ti serve una configurazione più mirata rispetto al widget ospitato? Crea la tua interfaccia con l'SDK JavaScript oppure contatta support@chattybox.ai per assistenza sull'architettura.

Supporto multilingue

Il widget risolve la lingua UI all’inizializzazione secondo la modalità fixed o auto del progetto; non osserva i cambi di route o lingua successivi.

Lingue ufficialmente supportate

Il widget ha cataloghi di traduzione per 14 lingue. La presenza di un catalogo non significa che ogni stringa visibile o accessibile sia tradotta, né garantisce la qualità delle risposte.

Lingua	Codice
Inglese	en
Francese	fr
Tedesco	de
Spagnolo	es
Italiano	it
Olandese	nl
Portoghese	pt
Polacco	pl
Svedese	sv
Indonesiano	id
Estone	et
Finlandese	fi
Gallese	cy
Ceco	cs

:::note Lingua dell'interfaccia e risposte La lingua dell'interfaccia non viene inviata come parametro della lingua della chat. Il backend rileva la lingua della domanda e tenta il recupero e la generazione consapevoli della lingua; lingua e qualità delle risposte dipendono dal contenuto indicizzato e dal modello. :::

Come funziona il rilevamento della lingua

Il widget usa un sistema di rilevamento a cascata:

1. Override dello script consentito – Un data-locale non vuoto prevale solo se allowLocaleOverride non è false, anche in modalità Fixed.
2. Modalità Fixed – Senza un override consentito, viene usato defaultLocale.
3. Modalità Auto – Viene usato il primo valore non vuoto tra <html lang> della pagina, navigator.language del browser (o il precedente userLanguage), quindi defaultLocale.
4. Normalizzazione – I valori regionali supportati, come fr-CA, sono ridotti al codice base; un valore non supportato passa subito all'inglese, senza provare il candidato successivo.

Override manuale della lingua

Per richiedere una lingua specifica indipendentemente dalle impostazioni del browser, abilita Allow Script Override e aggiungi l'attributo data-locale prima dell'avvio del loader:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-locale="de"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

:::tip Caso d'uso È particolarmente utile per un sito multilingue in cui ogni versione linguistica ha un proprio URL (ad esempio /de/, /fr/). Imposta data-locale in base alla lingua della pagina e verifica l'interfaccia renderizzata. :::

Impostazioni della lingua nella dashboard

La dashboard dell'app consente di configurare le preferenze linguistiche del widget per progetto:

• Auto-detect – Usa la lingua della pagina prima della lingua del browser del visitatore.
• Fixed Language – Usa la lingua predefinita configurata, salvo override data-locale consentito.
• Allow Script Override – Abilita o disabilita l'override tramite l'attributo data-locale.

Accedi a queste impostazioni dalla dashboard → Progetto → scheda Embed → sezione Widget Language.

Corrispondenza della lingua dei contenuti

Per un'esperienza multilingue utile, indicizza contenuti pubblici nelle lingue dei visitatori e verifica le fonti; rilevamento e recupero non sono garantiti. Per farlo:

1. Esegui lo scraping di tutte le versioni linguistiche della documentazione usando il file sitemap.xml.
2. Lo scraper tenta di rilevare la lingua della pagina; verifica contenuti e fonti.
3. Il recupero tenta di preferire la lingua della domanda, ma può usare altri contenuti indicizzati.

Configurazione nella dashboard dell'app: quando configuri lo scraping, usa l'URL sitemap.xml (ad esempio https://yourdocs.com/sitemap.xml) per individuare le versioni linguistiche, quindi verifica le pagine indicizzate. Le sitemap non aggirano limiti di crawl o esclusioni.

Risoluzione dei problemi

Il widget continua a essere visualizzato in inglese

• Ricaricamento completo come diagnosi – Ricarica con Ctrl+F5 o Cmd+Shift+R, poi controlla le richieste del widget e delle traduzioni nel pannello di rete del browser.
• Controlla data-locale – Verifica che l'attributo sia impostato correttamente con un codice lingua supportato.
• Verifica la lingua del browser – Controlla che la lingua preferita del browser sia impostata correttamente.
• Controlla lang nell'HTML della pagina – Assicurati che la pagina contenga <html lang="de"> (o il codice appropriato).

Le fonti sono nella lingua sbagliata

• Esegui nuovamente lo scraping dei contenuti – Assicurati che tutte le versioni linguistiche siano indicizzate.
• Usa sitemap.xml – Verifica che gli URL desiderati siano stati effettivamente indicizzati; limiti di crawl ed esclusioni possono ometterli.
• Controlla la lingua della query – L'AI cerca di adeguare la lingua della risposta a quella della query.

Mancano traduzioni

• Controlla le lingue supportate – Solo i 14 codici sopra elencati hanno cataloghi; le etichette mancanti possono usare il fallback inglese.

Best practice

1. Imposta <html lang> nelle pagine – Aiuta l'accessibilità e il rilevamento del widget.
2. Testa con data-locale durante lo sviluppo – Verifica che ogni lingua venga visualizzata correttamente.
3. Esegui lo scraping di tutte le versioni linguistiche – Usa sitemap.xml per la scoperta e verifica le pagine indicizzate.
4. Esamina le domande reali – Controlla le conversazioni e le lacune di contenuto specifiche per lingua; la dashboard non mostra attualmente una distribuzione delle locale del widget.