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 alla presentazione del widget salvate nella dashboard vengono applicate senza dover sostituire lo snippet sul sito.

---

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 forza facoltativamente una lingua specifica dell'interfaccia del widget per quella pagina.

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 ChattyBox si adatta automaticamente alle preferenze linguistiche dei visitatori e offre un'esperienza localizzata agli utenti di tutto il mondo.

Lingue ufficialmente supportate

L'interfaccia del widget (pulsanti, etichette e messaggi di sistema) è ufficialmente supportata in 14 lingue:

Lingua	Codice	UI del widget	Qualità delle risposte AI
Inglese	en	Supporto completo	Eccellente
Francese	fr	Supporto completo	Alta
Tedesco	de	Supporto completo	Alta
Spagnolo	es	Supporto completo	Alta
Italiano	it	Supporto completo	Alta
Olandese	nl	Supporto completo	Alta
Portoghese	pt	Supporto completo	Alta
Polacco	pl	Supporto completo	Alta
Svedese	sv	Supporto completo	Alta
Indonesiano	id	Supporto completo	Media
Estone	et	Supporto completo	Media
Finlandese	fi	Supporto completo	Media
Gallese	cy	Supporto completo	Media
Ceco	cs	Supporto completo	Media

:::note Supporto linguistico esteso Sebbene supportiamo ufficialmente 14 lingue per l'interfaccia del widget, l'AI sottostante può comprendere e rispondere in oltre 100 lingue. Tuttavia, non possiamo garantire risposte di alta qualità per le lingue al di fuori dell'elenco ufficiale. :::

Come funziona il rilevamento della lingua

Il widget usa un sistema di rilevamento a cascata:

1. Attributo data-locale – Ha la priorità più alta. Impostalo nel codice embed per forzare una lingua specifica.
2. Attributo <html lang> della pagina – Il widget controlla la lingua dichiarata della pagina.
3. Lingua del browser (navigator.language) – Usa le preferenze del browser del visitatore.
4. Fallback predefinito – Inglese se non viene rilevata alcuna lingua.

Override manuale della lingua

Per forzare la visualizzazione del widget in una lingua specifica indipendentemente dalle impostazioni del browser, aggiungi l'attributo data-locale:

<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 per un'esperienza coerente. :::

Impostazioni della lingua nella dashboard

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

• Auto-detect (consigliato) – Corrisponde automaticamente alla lingua del browser del visitatore.
• Fixed Language – Forza il widget a essere sempre visualizzato in una lingua specifica.
• 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 la migliore esperienza multilingue, il chatbot dovrebbe rispondere nella stessa lingua della domanda dell'utente. Per ottenerlo:

1. Esegui lo scraping di tutte le versioni linguistiche della documentazione usando il file sitemap.xml.
2. Lo scraper assegnerà automaticamente ai contenuti la relativa lingua.
3. Il sistema RAG recupererà la versione linguistica appropriata in base alla query.

Configurazione nella dashboard dell'app: quando configuri lo scraping, usa l'URL sitemap.xml (ad esempio https://yourdocs.com/sitemap.xml) per individuare e indicizzare automaticamente tutte le versioni linguistiche dei contenuti.

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 – In questo modo lo scraper troverà tutti gli URL /de/, /fr/ ecc.
• 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 le 14 lingue elencate sopra hanno traduzioni UI garantite.

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 un'indicizzazione multilingue completa.
4. Monitora la distribuzione delle lingue – Controlla Analytics per vedere quali lingue usano più spesso i visitatori.