Configurazione e personalizzazione del widget

Aggiungi al tuo sito un widget di chat basato su IA in meno di 5 minuti.

Configurazione rapida

Portare online il chatbot è semplice. Devi solo copiare un piccolo snippet di codice dalla dashboard.

Passaggio 1: recupera il codice di incorporamento

1. Apri la dashboard e seleziona il progetto.
2. Vai alla scheda Incorpora.
3. Scegli la chiave API da usare oppure creane una nuova.
4. Copia lo snippet di codice generato.

Passaggio 2: aggiungilo al sito

Incolla lo snippet subito prima del tag di chiusura </body> su ogni pagina in cui vuoi mostrare il widget.

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

:::tip Suggerimento È tutto. Non devi configurare colori o impostazioni nel codice: tutto viene gestito dalla dashboard. :::

---

Personalizzazione visiva

ChattyBox include un editor visivo integrato. Puoi adattare aspetto e comportamento del widget al tuo brand senza modificare codice.

Controlli nella dashboard

1. Colore accento - Scegli il colore principale del brand per launcher, evidenziazioni e messaggi utente.
2. Posizione - Scegli dove appare il widget sullo schermo.
3. Titolo intestazione - Imposta il titolo mostrato in alto nella finestra di chat.
4. Messaggio di benvenuto - Personalizza il primo messaggio visto dai visitatori.

nota

Le modifiche fatte nella dashboard vengono applicate subito. Non devi aggiornare il codice di incorporamento 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 devi ridistribuire il sito per piccole modifiche.

Usa la dashboard per colori, posizione, icona, titolo, messaggio di benvenuto, lingua predefinita, chiavi pubbliche, scraping e analisi.

Se il progetto usa restrizioni di origine per le chiavi pubbliche, mantienile allineate ai domini in cui il widget è installato.

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

• data-api-key identifica la chiave pubblica del widget.
• data-api-url indica al widget dove inviare le richieste.
• data-locale può forzare una lingua specifica per quella pagina.

Se il widget non appare dopo l'installazione, consulta la risoluzione dei problemi.

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

Nascondere il widget su pagine specifiche

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

.chattybox-widget {
  display: none;
}

Integrazioni personalizzate

Ti serve una configurazione più mirata rispetto al widget standard?

Contattaci a [email protected] e ti aiuteremo a scegliere l'approccio di integrazione più adatto.

Supporto multilingue

Il widget ChattyBox si adatta automaticamente alle preferenze linguistiche dei visitatori e offre un'esperienza localizzata.

Lingue ufficialmente supportate

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

Lingua	Codice	Interfaccia widget	Qualità risposte IA
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 Anche se l'interfaccia supporta ufficialmente 14 lingue, l'IA sottostante può capire e rispondere in oltre 100 lingue. Non possiamo però garantire la stessa qualità per lingue fuori dall'elenco ufficiale. :::

Come funziona il rilevamento della lingua

Il widget usa un sistema a cascata:

1. Attributo data-locale - Priorità massima. Impostalo nello snippet per forzare una lingua.
2. Attributo <html lang> della pagina - Il widget controlla la lingua dichiarata dalla pagina.
3. Lingua del browser (navigator.language) - Usa le preferenze del visitatore.
4. Fallback predefinito - Inglese se non viene rilevata alcuna lingua.

Sovrascrittura manuale della lingua

Per forzare una lingua indipendentemente dalle impostazioni del browser, aggiungi data-locale:

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

:::tip Caso d'uso È utile se il sito multilingue ha URL separati per ogni lingua, ad esempio /de/ o /fr/. Imposta data-locale in base alla lingua della pagina per mantenere un'esperienza coerente. :::

Impostazioni lingua nella dashboard

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

• Rilevamento automatico (consigliato) - Si adatta alla lingua del browser del visitatore.
• Lingua fissa - Forza sempre una lingua specifica.
• Consenti sovrascrittura da script - Abilita o disabilita l'uso di data-locale.

Trovi queste impostazioni nella dashboard → Progetto → Incorpora → Lingua widget.

Corrispondenza con la lingua dei contenuti

Per la migliore esperienza multilingue, il chatbot dovrebbe rispondere nella stessa lingua della domanda dell'utente. Per farlo:

1. Esegui lo scraping di tutte le versioni linguistiche della documentazione usando sitemap.xml.
2. Lo scraper etichetta automaticamente i contenuti con la lingua corretta.
3. Il sistema RAG recupera la versione linguistica adatta alla richiesta.

Configurazione nella dashboard: quando configuri lo scraping, usa l'URL sitemap.xml, ad esempio https://yourdocs.com/sitemap.xml, per trovare e indicizzare automaticamente tutte le versioni linguistiche.

Risoluzione dei problemi

Il widget mostra ancora l'inglese

• Svuota la cache del browser - Il file widget.js potrebbe essere in cache. Esegui un aggiornamento forzato (Ctrl+F5 / Cmd+Shift+R).
• Controlla data-locale - Verifica che l'attributo usi un codice lingua supportato.
• Controlla la lingua del browser - Assicurati che la preferenza sia corretta.
• Controlla HTML lang - La pagina deve usare <html lang="it"> o il codice adeguato.

Le fonti sono nella lingua sbagliata

• Ripeti lo scraping dei contenuti - Assicurati che tutte le versioni linguistiche siano indicizzate.
• Usa sitemap.xml - Così lo scraper trova gli URL /de/, /fr/ e simili.
• Controlla la lingua della domanda - L'IA prova ad allineare la risposta alla lingua della richiesta.

Traduzioni mancanti

• Controlla le lingue supportate - Solo le 14 lingue sopra elencate hanno traduzioni UI garantite.

Buone pratiche

1. Imposta <html lang> sulle pagine - Aiuta accessibilità e rilevamento del widget.
2. Testa con data-locale durante lo sviluppo - Verifica che ogni lingua venga mostrata 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 nelle analisi quali lingue usano di più i visitatori.