Incorpora il Widget di chat (Guida per sviluppatori)

Guida all'integrazione del widget

Il widget è un Web Component (<web-chat-agent>) che si carica in modo asincrono ed è eseguibile su qualsiasi sito, senza framework e senza fasi di compilazione. Lo script mostra un pulsante di chat mobile; i visitatori possono cliccarlo per aprire la finestra di chat.

Codice di incorporamento

Incolla questo codice subito prima del tag di chiusura </body>:

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
></web-chat-agent>

Sostituisci YOUR_CHATBOT_ID con il tuo ID del chatbot. Puoi trovare il codice di incorporamento precompilato in Dashboard → il tuo assistente → Canali → Widget di chat → Mostra dettagli di installazione e copiarlo direttamente da lì per evitare errori di battitura.

Il widget effettua le chiamate API alla stessa origine da cui è stato caricato. Caricando lo script da webchatagent.com, le richieste di chat vengono inviate automaticamente a webchatagent.com/api/..., senza dover configurare manualmente un URL API.

Come Funziona

1. Lo script async viene caricato in background e non blocca il rendering della pagina.
2. L'elemento <web-chat-agent> mostra un pulsante di chat mobile.
3. Il widget recupera le impostazioni dalla dashboard (colori, testi, strumenti, messaggio di benvenuto) e le applica. Non sono necessari attributi aggiuntivi.
4. Quando un visitatore clicca sul pulsante, si apre la finestra di chat e i messaggi vengono inviati al tuo chatbot IA.

Attributi HTML

Tutte le impostazioni visive configurate in Canali → Widget di chat vengono applicate automaticamente. Gli attributi HTML sull'elemento sono opzioni di override facoltative, da utilizzare solo per modifiche specifiche su singole pagine (ad esempio una posizione diversa su una specifica landing page). I nomi degli attributi usano il formato kebab-case (il widget mappa internamente theme-color alla proprietà themeColor).

I valori predefiniti indicati di seguito corrispondono ai fallback integrati del widget. Nella maggior parte dei casi gli attributi non vengono impostati e mantengono i valori configurati nella dashboard.

Impostazioni di Base

Colori

Tutti gli attributi relativi ai colori accettano qualsiasi valore CSS valido (codici esadecimali come #2563eb, rgb(), hsl()). Quando non vengono impostati, il widget utilizza il valore della dashboard o il fallback integrato (il colore predefinito del brand è il blu, #2563eb).

Immagini

Posizionamento

Contenuto & Comportamento

Aggiornamento del consenso a runtime

window.dispatchEvent(
  new CustomEvent('webchatagent:consent', {
    detail: { tracking: 'granted' }
  })
)

Invia denied quando il consenso viene rifiutato o revocato. I trigger locali anonimi rimangono disponibili. Consulta la guida al consenso sui cookie per la matrice dei trigger e gli adapter CMP.

Pulsanti di Suggerimento

Pulsanti di azione rapida posizionati sotto l'elenco messaggi. Ogni pulsante include un title visibile e un'action (il testo inviato come messaggio dell'utente al clic). Passa un array JSON come valore dell'attributo:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  prompt-buttons='[{"title":"Talk to support","action":"I need help with my order"},{"title":"Pricing","action":"What does it cost?"}]'
></web-chat-agent>

Session Context Data

Quando il widget è in esecuzione all'interno di un sistema che già conosce il visitatore, come un CRM, un portale clienti o un'area riservata, la pagina di incorporamento può passare queste informazioni al Chatbot. L'IA visualizza i valori, vi fa riferimento nelle sue risposte e li utilizza per compilare gli argomenti corrispondenti delle chiamate ai connettori API e agli strumenti MCP. Un visitatore il cui numero di pratica è già visibile sullo schermo non dovrà mai digitarlo di nuovo.

I dati di contesto vengono inviati con ogni richiesta di chat della sessione, vengono inseriti nel prompt dell'IA solo per quella specifica richiesta e non vengono memorizzati come record autonomi.

Passaggio del contesto tramite l'attributo HTML

Sono accettati due formati. Il formato semplice non richiede alcuna conoscenza di JSON, solo coppie Key=Value separate da punto e virgola:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data="Customer=Jane Doe;Company=Acme GmbH;OrderID=A-1023"
></web-chat-agent>

Solo il primo = in ciascuna coppia separa la chiave dal valore, quindi i valori che contengono = (ad esempio i token base64) rimangono intatti. In questo formato un valore non può contenere un punto e virgola, per tali casi si utilizza JSON:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data='{"Customer":"Jane Doe","Note":"VIP; priority support","OrderID":"A-1023"}'
></web-chat-agent>

Con JSON, racchiudi il valore dell'attributo tra virgolette singole, in modo che le virgolette doppie interne vengano mantenute.

Passaggio del contesto tramite JavaScript

Se preferisci JavaScript rispetto all'attributo (o se è necessario, ad esempio su WordPress), imposta la variabile globale window.webchatagentContext. Può essere impostata in sicurezza prima del caricamento dello script del widget: il widget la recupera al momento dell'inizializzazione, quindi l'ordine di caricamento degli script non ha importanza:

<script>
  window.webchatagentContext = {
    Customer: 'Jane Doe',
    OrderID: 'A-1023',
    userToken: 'opaque-token-validated-by-your-backend'
  }
</script>
<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>

Aggiornamento del contesto a runtime

Quando i dati cambiano mentre il widget è già in esecuzione (accesso dell'utente, passaggio a un'altra pratica), invia l'evento webchatagent:context con un oggetto semplice:

window.dispatchEvent(
  new CustomEvent('webchatagent:context', {
    detail: {
      Topic: 'billing',
      OrderID: 'A-1023'
    }
  })
)

Ogni evento sostituisce l'intero contesto; detail: null o {} lo azzera. Ordine di precedenza al caricamento: viene applicato prima l'attributo context-data, poi window.webchatagentContext (se impostato), quindi gli eventuali eventi. Il contesto risiede nella pagina, dopo una ricarica è necessario impostarlo nuovamente.

Distribuzioni white-label: gli alias neutrali rispetto al brand window.chatWidgetContext (globale) e chat-widget:context (evento) funzionano in modo identico, evitando che le pagine di incorporamento debbano fare riferimento al nome della piattaforma.

Limiti

Al massimo 20 chiavi, nomi di chiave fino a 64 caratteri, valori fino a 500 caratteri (numeri e booleani vengono convertiti in stringhe), 4.000 caratteri in totale. Le interruzioni di riga e i caratteri < > vengono rimossi da chiavi e valori. Le risposte alle richieste che includono dati di contesto non vengono mai recuperate dalla cache delle risposte.

Sicurezza: i dati di contesto non costituiscono autenticazione

I valori provengono dal browser del visitatore. Chiunque può aprire gli strumenti di sviluppo (DevTools) e inviare un contesto arbitrario, pertanto l'IA è istruita a trattarlo come dato di base non verificato. Non basare mai le autorizzazioni su di esso.

Due regole per l'uso in produzione:

1. Limita allowedDomains per il tuo Chatbot nella dashboard. In assenza di questa configurazione, qualsiasi pagina può incorporare il bot e trasmettergli un contesto.
2. Per la ricerca di dati personali, passa un token opaco invece dell'identità in chiaro. Genera lato server un token a breve durata per l'utente autenticato, passalo come valore di contesto (ad esempio userToken=...) e lascia che l'endpoint del tuo connettore API convalidi il token prima di restituire i dati dell'utente. L'IA inoltra il token nella chiamata API; il tuo backend decide cosa sbloccare. Un token contraffatto non restituirà alcun dato.

WordPress

Il plugin WordPress (a partire dalla sua prossima versione) supporta i dati di contesto lato server: il filtro webchatagent_context_data li fornisce per il widget mobile (e come impostazione predefinita per le integrazioni inline), mentre lo shortcode inline accetta l'attributo context-data:

add_filter('webchatagent_context_data', function () {
    $user = wp_get_current_user();
    return $user->exists() ? 'Customer=' . $user->display_name : '';
});

[webchatagent_inline context-data="Topic=Support;OrderID=A-1023"]

Nelle versioni precedenti del plugin, imposta window.webchatagentContext o invia l'evento webchatagent:context, entrambi funzionano su qualsiasi piattaforma.

Esempio: Personalizzazione completa

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="abc-123-def"
  theme="modern"
  title="Support Chat"
  theme-color="#4f46e5"
  theme-text-color="#ffffff"
  user-message-color="#4f46e5"
  bubble-color="#4f46e5"
  font-family="Inter"
  initially-open="false"
  offset-x="30"
  offset-y="30"
></web-chat-agent>

Dashboard rispetto agli attributi HTML

Le impostazioni della dashboard vengono memorizzate lato server e caricate all'inizializzazione del widget. Gli attributi HTML le sovrascrivono esclusivamente per quella pagina.

Raccomandazione: Configura tutta la personalizzazione visiva nella dashboard. Ricorri agli attributi HTML solo quando una pagina specifica necessita di differenze, come un posizionamento diverso, un tema forzato o pulsanti suggerimento dedicati alla pagina.

CSS personalizzato

Per modifiche più avanzate rispetto agli attributi sopra indicati, puoi applicare il tuo CSS agli elementi interni del widget. Ogni elemento stilizzabile include una classe stabile .wca-* (ad esempio .wca-header, .wca-message, .wca-bubble), in questo modo i selettori continuano a funzionare anche dopo gli aggiornamenti del widget e non richiedono !important. Il CSS viene aggiunto nella dashboard e iniettato nello Shadow DOM del widget. Consulta CSS personalizzato.

Chat integrata

Per visualizzare la chat all'interno del layout della pagina invece di utilizzare un pulsante mobile, usa la variante inline. Questa carica uno script differente e un elemento dedicato (<web-chat-agent-inline>):

<script src="https://webchatagent.com/widget/chat-widget-inline.js" async></script>
<web-chat-agent-inline chatbot-id="YOUR_CHATBOT_ID"></web-chat-agent-inline>

L'elemento inline accetta chatbot-id, un parametro opzionale container-height, oltre a tracking-consent e context-data (consulta Session Context Data, l'attributo e l'evento a runtime funzionano in modo identico anche qui); tutte le altre impostazioni provengono da Canali → Chat integrata. Posiziona l'elemento nel punto desiderato della pagina e dimensionale tramite il contenitore circostante. Consulta Chat integrata per maggiori dettagli.

WordPress

Su WordPress, utilizza il WebChatAgent WordPress Plugin ufficiale invece di incollare lo script manualmente. Gestisce l'incorporamento e gli aggiornamenti in modo automatico. Consulta WordPress Plugin.

Single Page Application (SPA)

Il widget supporta nativamente React, Vue, Angular e altre SPA. Aggiungi il tag di script a index.html e inserisci l'elemento <web-chat-agent> nella struttura principale dell'applicazione (ad esempio nel root layout). Il widget rimane attivo durante i cambi di route lato client e non deve essere rimontato a ogni navigazione.