Documentazione

Widget JavaScript

Aggiungi il widget di chat a qualsiasi sito web con un semplice tag script.

Il widget JavaScript è il modo più semplice per aggiungere il tuo agente a qualsiasi sito web. Un unico tag script crea una chat bubble fluttuante su cui i visitatori possono cliccare per iniziare una conversazione.

Configurazione rapida

  1. Vai alla scheda Pubblica del tuo agente
  2. Seleziona Chat Widget (predefinito)
  3. Copia lo snippet JavaScript mostrato
  4. Incollalo nel tuo sito web prima di </body>
  5. Salva e aggiorna il tuo sito web

La chat bubble appare nell'angolo della pagina. Il tuo snippet include l'ID specifico del tuo agente e l'URL corretto dello script.

Configurazione del widget

Posizione

Il widget appare nell'angolo in basso a destra per impostazione predefinita. Cambia la posizione nelle impostazioni Design.

Colori

I colori del widget seguono il tema del tuo agente. Personalizzali nella scheda Design.

Dispositivi mobili

Il widget è completamente responsive e funziona automaticamente sui dispositivi mobili.

Allegati file

I visitatori possono allegare documenti, fogli di calcolo, immagini e file di testo direttamente dal widget. Gli allegati vengono usati solo come contesto temporaneo della conversazione e non vengono aggiunti alle fonti di addestramento del tuo agente.

I formati supportati includono PDF, Word, Excel, HTML, TXT, Markdown, JSON, CSV, PNG, JPG, WEBP e GIF. I visitatori possono allegare fino a 3 file per messaggio, con un limite di 10 MB per file. I PDF vengono analizzati fino alle prime 20 pagine per mantenere le risposte rapide e affidabili.

Attributi dati

Il widget usa attributi dati per la configurazione:

AttributoDescrizionePredefinito
data-chatbotObbligatorio. L'ID del tuo agente (incluso nel tuo codice di embed)-

Posizionamento

Dove aggiungere il codice

Aggiungi lo script appena prima di </body> per prestazioni ottimali:

<!DOCTYPE html>
<html>
<head>
  <!-- Your head content -->
</head>
<body>
  <!-- Your website content -->

  <!-- Paste your embed code from Chatbot > Publish here -->
</body>
</html>

Single-page application

Per le SPA, aggiungi lo script al tuo template HTML principale o al file index.

Pagine multiple

Aggiungi lo stesso script a ogni pagina in cui vuoi che appaia il widget. Oppure aggiungilo al template di layout del tuo sito.

Testare l'installazione

Dopo aver aggiunto il codice:

  1. Visita il tuo sito web in un browser
  2. Cerca la chat bubble (in basso a destra per impostazione predefinita)
  3. Clicca per aprire la chat
  4. Invia un messaggio di prova
  5. Verifica che la risposta sia corretta

Risoluzione dei problemi

Il widget non appare:

  • Controlla che lo script sia prima di </body>
  • Verifica che l'ID dell'agente sia corretto
  • Svuota la cache del browser
  • Controlla la console del browser per eventuali errori

Posizione errata:

  • Controlla le impostazioni Design
  • Cerca conflitti CSS

Non risponde:

  • Assicurati che esistano contenuti di addestramento
  • Controlla i limiti di messaggi del piano
  • Prova prima nel Playground

Restrizioni di dominio

Se hai configurato i domini consentiti:

  • Il widget si carica solo sui domini approvati
  • Gli altri siti non vedono il widget (nessun errore mostrato)

Configura i domini →

Prestazioni

Il widget è ottimizzato per un impatto minimo:

  • Si carica in modo asincrono (attributo async)
  • Bundle di dimensioni ridotte
  • Nessun blocco del rendering
  • Caricamento lazy dell'interfaccia di chat

Conflitti di stile

Il widget usa stili isolati e non dovrebbe entrare in conflitto con il tuo sito. Se riscontri problemi:

  1. Controlla i selettori CSS globali
  2. Cerca regole !important
  3. Contatta il supporto se i problemi persistono

Rimuovere il widget

Per rimuoverlo:

  1. Elimina il tag script dal tuo HTML
  2. Svuota eventuali cache
  3. Il widget scompare immediatamente

Prossimi passi