Installa il widget

Il widget di RolChat è un unico pulsante flottante che si adatta ai moduli che hai attivato: chat, modulo di richiesta di richiamata, prenotazione di appuntamenti, modulo lead e ricerca nella base di conoscenza vivono tutti al suo interno. Lo installi una volta; cosa mostra lo decidi dalla dashboard.

1. Copia lo snippet

In Impostazioni → Widget, scegli il sito e copia lo snippet di installazione. Ha questo aspetto:

<!-- RolChat widget -->
<script>
  window.rolchatConfig = {
    "site_id": "ste_…",
    "account_id": "…",
    "widget_key": "wk1.<site>.<signature>",
    "modules": ["chat"]
  };
</script>
<script async src="https://widget.rolchat.com/stub.js"></script>

La chiave del widget è pubblica e può essere inclusa in una pagina senza rischi. Identifica il tuo sito ed è firmata, quindi nessuno può puntare una copia del widget sul tuo account. Man mano che modifichi le impostazioni del widget, la dashboard aggiunge altre chiavi all’oggetto (saluto, titolo dell’intestazione, tema, orari di lavoro, layout per viewport); copia di nuovo lo snippet dopo averle cambiate, oppure lascia l’oggetto minimo e lascia che il widget recuperi il resto.

stub.js pesa pochi kilobyte e carica il resto solo quando serve al visitatore: l’interfaccia della chat alla prima apertura, il tracciamento dopo il consenso, il banner dei consensi dove è richiesto.

2. Incollalo prima di </body>

Aggiungi lo snippet a ogni pagina in cui vuoi il widget, idealmente tramite il template del sito o il tag manager, così compare ovunque in un colpo solo. Lo script si carica in modo asincrono e non blocca il rendering; il bundle del primo caricamento è volutamente leggero per non incidere sui tuoi Core Web Vitals.

3. Verifica che funzioni

Apri il tuo sito in una finestra privata. Il pulsante compare nell’angolo che hai scelto. Nella dashboard, Visitatori mostra in tempo reale la nuova sessione anonima, e un messaggio inviato dal widget arriva nella Posta in arrivo come nuova conversazione.

Identificare gli utenti che hanno effettuato l’accesso

Se i tuoi visitatori accedono al tuo prodotto, comunica a RolChat chi sono, così le conversazioni si collegano al contatto giusto:

window.rolchat.identify({
  email: "alice@example.com",
  first_name: "Alice",
  last_name: "Martin",
  phone: "+15551234567",
  external_id: "user_12345",
  custom_fields: { plan: "pro" },
});

Gli attributi accettati sono email, phone, first_name, last_name, external_id e un oggetto piatto custom_fields; tutto il resto viene ignorato. RolChat cerca l’email nel CRM. Se il contatto esiste, la sessione viene collegata a esso e l’agente vede il profilo; in caso contrario i dati vengono conservati e si crea un lead quando il visitatore scrive per la prima volta.

Per un livello di fiducia maggiore, il tuo backend può firmare l’identità: passa insieme agli attributi la firma che RolChat emette per l’utente, e la sessione viene promossa solo se la firma è valida. Chiama window.rolchat.reset() quando l’utente si disconnette, altrimenti la persona successiva su quel browser vede la conversazione precedente.

L’API JavaScript

window.rolchat è disponibile non appena lo stub viene eseguito; le chiamate effettuate prima del caricamento del bundle vengono messe in coda ed eseguite in ordine.

Metodo	Cosa fa
show() / hide()	Mostra o nasconde il pulsante di avvio
open() / close()	Apre o chiude il pannello della chat
identify(traits)	Collega la sessione a una persona (vedi sopra)
reset()	Dimentica l’identità e avvia una nuova sessione anonima
pushEvent(name, props)	Segnala un evento personalizzato per messaggi trigger e automazione
trackPageView(path?)	Segnala una visualizzazione di pagina nelle single-page app
setLocale(code)	Cambia la lingua del widget
showConsentPreferences()	Apre il centro preferenze dei consensi
on(event, handler) / off(event, handler)	Iscrizione a chat:opened, chat:closed, message:sent, message:received, session:started

window.rolchat.pushEvent("cart_abandoned", { value: 129.9, currency: "EUR" });
window.rolchat.on("message:received", () => audio.play());

Lingua e direzione

Il widget parla la lingua che fissi con lang in window.rolchatConfig (per esempio "lang": "de"); senza di essa, la lingua del browser del visitatore, presa nell’ordine delle preferenze del browser tra le 40 lingue supportate da RolChat; se nessuna corrisponde, l’inglese. L’impostazione della lingua del sito stesso non viene usata: per far parlare al widget la lingua del tuo sito, imposta lang. Arabo ed ebraico vengono visualizzati da destra a sinistra. I messaggi degli agenti non vengono tradotti dal widget; lato agente si può usare invece la traduzione live con l’AI.

Cookie e consenso

Il widget non traccia i visitatori prima del consenso dove è richiesto un banner dei consensi. Se usi il modulo Privacy di RolChat, il banner e il widget condividono un unico stato del consenso. Se usi un altro strumento per i consensi, gli eventi analitici del widget attendono il segnale che configuri in Impostazioni → Privacy → Incorporamento.

Dove si configura il widget

Cosa	Dove
Colori, posizione, saluto, punti di accesso, snippet di installazione	Impostazioni → Widget
Quali moduli compaiono nel widget	Impostazioni → Moduli (per sito)
Orari di lavoro e messaggio offline	Impostazioni → Siti → Orari di lavoro
Messaggi trigger mostrati su pagine specifiche	Marketing → Trigger