# API JavaScript del widget

> Il tag, l'oggetto window.SupportFast, le opzioni, gli eventi, le variabili CSS e i limiti tecnici del widget, per chi sviluppa il sito.

Pagina: https://supportfast.ai/it/guida/sviluppatori/widget-api/ · Sezione: Sviluppatori · Aggiornata il 30 ottobre 2026

Per installare il widget senza scrivere codice parti da [Installare il widget](https://supportfast.ai/it/guida/sito-web/installa-widget.md).

## Cosa resta stabile fra le versioni

Questi elementi non cambiano nome né significato fra una versione e l'altra:

- Il file `chatbot.js`, incluso come script classico, con `id="supportfast-script"` (o `id="chatbot-script"`) e l'attributo `data-chatbot-id`.
- L'oggetto `window.SupportFast`, con `init()` e `version`.
- `window.ChatbotConfig.lang` e `window.chatbotUserData`.
- L'evento `chatbot_open` nel `dataLayer`.
- Il contenitore `#chat-widget-container`, a cui si applicano le variabili CSS.
- Le variabili CSS `--sf-offset-bottom`, `--sf-offset-side` e `--sf-z-index`.

Il resto, comprese le classi interne del widget, può cambiare: non usarlo nel codice del sito.

## Il tag

**HTML · il tag del widget (codice agente d'esempio)**

```
<script defer id="supportfast-script" src="https://cdn.supportfast.ai/chatbot.js" data-chatbot-id="bot-a1b2c3d4e5"></script>
```

| Attributo | Valore | Note |
| --- | --- | --- |
| `id` | `supportfast-script` oppure `chatbot-script` | Obbligatorio. Lascia quello del codice che ti dà la console. |
| `src` | L'indirizzo di `chatbot.js` | Obbligatorio. Non ospitare il file sul tuo server: il widget carica le sue parti dalla stessa cartella. |
| `data-chatbot-id` | Il codice dell'agente | Obbligatorio. Senza, il widget non parte. |
| `defer` | — | Consigliato, ed è già nel codice della console. Il widget funziona anche con `async` o senza nessuno dei due, ma il tuo codice deve aspettarlo come spiegato [più sotto](https://supportfast.ai/it/guida/sviluppatori/widget-api.md#attendere). |

- Il tag deve restare uno script classico: non aggiungere `type="module"`.
- Va incluso una volta per pagina. Una seconda inclusione non fa nulla.
- Il widget si monta quando il documento è pronto. Se il tag arriva dopo, per esempio da Google Tag Manager, si monta subito.

## L'oggetto window.SupportFast

Il widget crea `window.SupportFast` appena `chatbot.js` viene eseguito, prima che la chat sia pronta.

| Membro | Cosa fa |
| --- | --- |
| `version` | La versione del widget che gira sulla pagina. |
| `init()` | Monta il widget, se non è già montato. Parte da sola quando il documento è pronto; chiamarla di nuovo non crea doppioni. Se il tuo framework ha tolto il contenitore, lo rimonta. |
| `open()`, `close()`, `toggle()` | Aprono, chiudono o alternano la chat. |
| `identify(dati)` | Sostituisce i dati del cliente collegato. Senza argomenti rilegge `window.chatbotUserData`. |
| `on(evento, gestore)`, `off(evento, gestore)` | Ascoltano, o smettono di ascoltare, gli eventi `ready`, `open` e `close`. |

- Le chiamate fatte dopo l'esecuzione di `chatbot.js`, ma prima che la chat sia pronta, restano in coda e partono nell'ordine di arrivo.
- `ready` arriva quando l'agente è caricato e attivo; un gestore registrato dopo parte subito. Con l'agente non disponibile, non arriva.

**HTML · un bottone del sito che apre la chat**

```
<button type="button" onclick="window.SupportFast && window.SupportFast.open()">Scrivici</button>
```

### Far aspettare il tuo codice

Prima che `chatbot.js` venga eseguito, `window.SupportFast` non esiste e non c'è una coda in cui lasciare le chiamate. Il tuo codice deve quindi aspettare l'oggetto.

- **Con il tag in `defer`**, come nel codice della console, basta l'evento `DOMContentLoaded`: arriva dopo l'esecuzione degli script `defer`.
- **Con `async`, con Google Tag Manager o con un plugin che ritarda gli script**, `chatbot.js` può arrivare dopo `DOMContentLoaded`. Usa la funzione qui sotto, che va bene in tutti i casi.

**JavaScript · aspettare il widget, comunque sia caricato**

```
function conSupportFast(azione) {
  var tentativi = 0;
  (function prova() {
    if (window.SupportFast && typeof window.SupportFast.on === "function") {
      azione(window.SupportFast);
    } else if (tentativi < 100) {
      tentativi += 1;
      setTimeout(prova, 100); // riprova ogni decimo di secondo, per 10 secondi
    }
  })();
}

conSupportFast(function (chat) {
  chat.on("ready", function () {
    // la chat è caricata e l'agente è attivo
  });
});
```

Se `chatbot.js` può arrivare più tardi, per esempio perché un plugin aspetta il primo movimento del visitatore, alza il numero di tentativi.

## Forzare la lingua: window.ChatbotConfig.lang

Di norma il widget sceglie la lingua dal browser del visitatore, fra quelle del workspace. Per forzarla, imposta `window.ChatbotConfig` prima del codice del widget.

**HTML · chat sempre in inglese**

```
<script>window.ChatbotConfig = { lang: "en" };</script>
<script defer id="supportfast-script" src="https://cdn.supportfast.ai/chatbot.js" data-chatbot-id="bot-a1b2c3d4e5"></script>
```

- Codici possibili, in minuscolo: `it`, `en`, `de`, `fr`, `es`, `nl`, `pl`, `tr`, `pt`, `pt-br`, `sr`. `it-IT` o `IT` non valgono.
- La lingua deve essere fra quelle del workspace. Altrimenti il widget la ignora e sceglie come al solito.
- La lingua si decide all'avvio: per cambiarla serve ricaricare la pagina.
- Vale solo per il widget installato con il codice nel sito, non per il link e l'iframe.

## I dati del cliente collegato: window.chatbotUserData

Con `window.chatbotUserData` passi al widget i dati di un cliente collegato al tuo sito. I campi sono `firstName`, `lastName`, `fullName`, `company`, `email`, `phone` e `metadata`, per le variabili del workspace. Limiti ed esempi sono in [Passare i dati dell'utente](https://supportfast.ai/it/guida/sito-web/dati-utente.md).

## Eventi per Google Analytics e Tag Manager

A ogni apertura della chat il widget esegue `window.dataLayer.push({ event: "chatbot_open" })`. Se `dataLayer` non esiste, lo crea. L'evento non ha altri parametri.

**Con Google Tag Manager** crea un attivatore di tipo evento personalizzato, con nome evento `chatbot_open`. Collegalo a un tag evento di Google Analytics 4, per esempio con lo stesso nome. Pubblica il contenitore, apri la chat e cerca l'evento nel rapporto in tempo reale di Analytics.

**Con gtag.js, senza Tag Manager**, una voce nel `dataLayer` non diventa un evento di Analytics. Usa l'evento `open` del widget:

**JavaScript · evento GA4 all'apertura della chat**

```
// conSupportFast è la funzione di «Far aspettare il tuo codice», qui sopra
conSupportFast(function (chat) {
  chat.on("open", function () {
    gtag("event", "chatbot_open");
  });
});
```

La chat dentro un iframe comunica con la pagina che la contiene attraverso messaggi `postMessage`, elencati in [Passare i dati dell'utente](https://supportfast.ai/it/guida/sito-web/dati-utente.md#iframe).

## Spostare il bottone: le variabili CSS

Il contenitore del widget legge tre variabili CSS, che puoi impostare dal foglio di stile del sito:

| Variabile | Predefinito | Cosa cambia |
| --- | --- | --- |
| `--sf-offset-bottom` | `30px` | La distanza del bottone dal fondo dello schermo. |
| `--sf-offset-side` | `25px` | La distanza dal lato, destro o sinistro secondo la Posizione del bottone. |
| `--sf-z-index` | `2147483647` | Il livello di sovrapposizione: il valore predefinito è il più alto possibile. |

**CSS · bottone più in alto, per non coprire un banner dei cookie**

```
#chat-widget-container {
  --sf-offset-bottom: 100px; /* il bottone sale sopra il banner, alto circa 80 pixel */
  --sf-offset-side: 20px;
  --sf-z-index: 1000; /* più basso del predefinito: il banner, se ha un livello più alto, resta sopra la chat */
}
```

- Puoi scriverle su `#chat-widget-container` o su un elemento che lo contiene, come `:root`.
- La finestra aperta e la nuvola si spostano con il bottone. Sotto i 600 pixel di larghezza la finestra aperta occupa comunque tutto lo schermo.
- Abbassa `--sf-z-index` se un elemento del sito, come un menu o il banner dei cookie, deve stare sopra la chat: passa sopra ogni elemento con un livello più alto del valore che scegli.
- Per nascondere il widget in una pagina, applica solo lì la regola `#chat-widget-container { display: none; }`. Serve, per esempio, nella pagina in cui hai messo la chat con l'[iframe](https://supportfast.ai/it/guida/sito-web/pagina-intera-iframe.md#iframe).

## Isolamento dal CSS del sito

La chat è isolata dal resto della pagina: il CSS del sito non entra nella chat e quello della chat non esce. Dal sito si governano solo il contenitore e le tre variabili CSS.

## Content Security Policy

Se il sito manda una Content Security Policy (CSP), la policy deve permettere gli indirizzi da cui il widget carica le sue parti e con cui comunica. Altrimenti il bottone non compare, o la chat si apre ma non risponde. Aggiungi queste origini alle direttive che il sito usa già:

| Direttiva | Origini da aggiungere | A cosa serve |
| --- | --- | --- |
| `script-src` | `https://cdn.supportfast.ai` | `chatbot.js` e le parti del widget, che arrivano dalla stessa cartella. |
| `font-src` | `https://cdn.supportfast.ai` | Il carattere della chat. |
| `connect-src` | `https://server.supportfast.ai` e `wss://server.supportfast.ai` | L'agente, i messaggi, l'invio degli allegati e gli aggiornamenti in tempo reale, per esempio le risposte degli operatori. |
| `img-src` | `https:` e `blob:` | La foto o il logo dell'agente, le immagini nelle risposte, gli allegati e l'anteprima di una foto prima dell'invio. Le immagini arrivano da più indirizzi, anche temporanei: per questo serve `https:`. |
| `media-src` | `https:` | L'ascolto dei messaggi vocali nella chat. |
| `frame-src` | `https://app.supportfast.ai` | Solo se metti la chat in una pagina con l'[iframe](https://supportfast.ai/it/guida/sito-web/pagina-intera-iframe.md#iframe): è l'indirizzo che trovi nel codice dell'iframe. |

**HTTP · esempio di intestazione con le sole direttive del widget**

```
Content-Security-Policy:
  script-src 'self' https://cdn.supportfast.ai;
  font-src 'self' https://cdn.supportfast.ai;
  connect-src 'self' https://server.supportfast.ai wss://server.supportfast.ai;
  img-src 'self' https: blob:;
  media-src 'self' https:;
  frame-src 'self' https://app.supportfast.ai
```

- Il widget non ha bisogno di `'unsafe-inline'` né di `'unsafe-eval'`. Gli script che scrivi tu nella pagina, come `window.chatbotUserData` o `window.ChatbotConfig`, sono invece script in linea: con una policy senza `'unsafe-inline'` dagli un `nonce` o spostali in un file.
- Per i messaggi vocali il browser deve concedere il microfono alla pagina. Se il sito manda l'intestazione `Permissions-Policy`, deve contenere `microphone=(self)`. Nell'iframe il codice della console ha già `allow="microphone"`.
- Sul portale di un rivenditore gli indirizzi possono essere diversi: per `script-src`, `font-src` e `frame-src` usa i domini che trovi nel codice copiato dalla console.

**Come verificare.** Apri il sito, poi la console del browser (`F12`), e apri la chat. Se la policy blocca qualcosa, la console mostra un errore che nomina la direttiva e l'indirizzo bloccato: aggiungilo e riprova.

## Cosa salva nel browser

Il widget usa solo il `localStorage`: nessun cookie, niente `sessionStorage` né IndexedDB. Con il bottone i dati stanno sul dominio del tuo sito; con il link e l'iframe sul dominio della chat.

- Il consenso alla privacy dato dal visitatore vale fino allo stesso giorno del mese dopo. Una conversazione ferma da più di 31 giorni non si riapre da sola.
- Le chiavi del widget cominciano con `sf:`. Se un gestore dei cookie svuota il `localStorage`, escludile: altrimenti la chat riparte da zero a ogni visita.
- Se il browser nega il `localStorage`, il widget funziona senza memoria.

## Messaggi nella console del browser

Durante il funzionamento normale il widget non scrive nella console. Quando qualcosa non va, scrive un messaggio in inglese che comincia con `[SupportFast]`:

| Messaggio | Cosa significa |
| --- | --- |
| `script tag not found: it needs id="supportfast-script" or id="chatbot-script" and a src.` | Il tag non ha l'`id` giusto o il `src`. Controlla anche che un plugin non abbia tolto l'`id`. |
| `data-chatbot-id is missing on the script tag.` | Manca il codice dell'agente. |
| `the widget could not be loaded.` | Le parti del widget non sono arrivate: rete, [Content Security Policy](https://supportfast.ai/it/guida/sviluppatori/widget-api.md#csp), oppure `chatbot.js` copiato sul tuo server. |

Alcuni casi non producono messaggi: agente in pausa, codice inesistente, dominio non autorizzato, browser troppo vecchio. Le cause e i rimedi sono in [Problemi con il widget sul sito](https://supportfast.ai/it/guida/aiuto/problemi-widget.md).

## Browser supportati

Il widget funziona su Chrome ed Edge dalla versione 85, su Firefox dalla 101 e su Safari dalla 16.4. Su iPhone e iPad serve iOS o iPadOS 16.4 o successivo. Sui browser più vecchi il bottone non compare, senza conseguenze per il resto della pagina.

I messaggi vocali richiedono anche un browser che sappia registrare l'audio e l'accesso al microfono. Dove mancano, il microfono non compare.

## Versioni e aggiornamenti

Il tag punta sempre allo stesso `chatbot.js`: le versioni nuove arrivano da sole, senza toccare il sito. Per sapere quale versione gira, scrivi `window.SupportFast.version` nella console del browser.

## Leggi anche

- [Installare il widget](https://supportfast.ai/it/guida/sito-web/installa-widget.md): Il codice, il dominio di pubblicazione e la verifica.

- [HTML e altri siti](https://supportfast.ai/it/guida/sito-web/altri-siti.md): HTML, Google Tag Manager, costruttori di siti, Joomla e PrestaShop.

- [Problemi con il widget sul sito](https://supportfast.ai/it/guida/aiuto/problemi-widget.md): I problemi più comuni, per sintomo.