Documentazione

Widget JavaScript

Installa il widget di chat con il codice completo generato in Canali.

Il widget JavaScript aggiunge una chat bubble fluttuante al tuo sito. Il codice generato contiene due tag script; copiali entrambi dalla scheda Canali del tuo agente.

Configurazione rapida

  1. Apri Canali → Incorporamento nel sito web per il tuo agente
  2. Seleziona Widget di chat e attiva il canale
  3. Copia il codice generato completo, inclusi entrambi i tag script
  4. Incollalo nel tuo sito web prima di </body>
  5. Salva e aggiorna il tuo sito web

Il primo tag prepara la coda dei comandi di Agentkit. Il secondo carica il widget con l’ID del tuo agente e l’URL dello script configurato. Mantieni insieme i due tag e i loro valori.

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

Incolla entrambi i tag script generati prima di </body>:

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

  <!-- Paste both script tags from Channels > Website embed here -->
</body>
</html>

Single-page application

Per le SPA, aggiungi il codice generato completo al template HTML principale o al file index.

Pagine multiple

Aggiungi lo stesso codice generato a ogni pagina in cui vuoi mostrare il widget, oppure inseriscilo in un template di layout condiviso.

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 nel codice sorgente visualizzato che entrambi i tag script siano 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. Rimuovi entrambi i tag script generati dal tuo HTML
  2. Svuota eventuali cache
  3. Il widget scompare immediatamente

Prossimi passi