Developer

Documentazione completa del widget

Il widget carica automaticamente la configurazione dalle API AISA. Gli attributi data-* servono quasi sempre come override puntuali: usali solo quando vuoi forzare un comportamento lato pagina.

Config precedence

Ordine effettivo di risoluzione

Override inline

Ogni attributo data-* presente nello script ha priorità massima e forza solo quella singola opzione.

Configurazione remota

Se un override non è presente, il widget usa le impostazioni recuperate dalle API AISA tramite API URL e agent ID.

Default interni

Solo se manca anche il valore remoto, il widget applica il proprio fallback locale documentato nel README.

Cosa è davvero obbligatorio

Per il bootstrap reale ti bastano data-api-url e data-agent-id. Aggiungi data-identity e data-context solo se vuoi passare dati utente o contesto runtime al backend.

data-api-url

Endpoint della tua istanza assistant. Senza questo il widget non può recuperare la config remota.

data-agent-id

Identificatore dell'agente usato per caricare impostazioni e instradare la conversazione all'assistente corretto.

data-identity

Opzionale. Stringa o JSON con dati come name, email e phone, inviati al backend tramite un evento identity dedicato.

data-context

Opzionale. Stringa extra per dare contesto alla sessione, utile per pagina, funnel, campagna o caso d'uso.

Snippet minimo

Installazione consigliata

Produzione

Questo è il setup che consigliamo nella maggior parte dei casi: lo script identifica ambiente e agente, poi recupera il resto dal backend. Identità e contesto sono opzionali.

<script
  src="https://cdn.jsdelivr.net/gh/Autocust/ai-chat-widget@latest/dist/chat-widget.min.js"
  data-api-url="https://assistant.aisalesassistant.it"
  data-agent-id="AGENT_ID"
  data-identity='{"email":"[email protected]"}'
  data-context="Landing pricing enterprise"
></script>

Snippet con override

Quando forzare opzioni locali

Eccezioni

Questo esempio mostra alcune personalizzazioni inline. Sono tutte facoltative e sovrascrivono il valore remoto corrispondente.

<script
  src="https://cdn.jsdelivr.net/gh/Autocust/ai-chat-widget@latest/dist/chat-widget.min.js"
  data-api-url="https://assistant.aisalesassistant.it"
  data-agent-id="AGENT_ID"
  data-theme="dark"
  data-position="bottom-right"
  data-predefined-questions='["Prezzi","Onboarding","Integrazioni"]'
  data-button-overlay-text="Serve una mano?"
  data-start-open="false"
  data-width="360px"
></script>

Reference

Attributi supportati

Ogni attributo qui sotto è disponibile nel widget. Se non lo imposti inline, il widget usa prima la configurazione remota dell'agente e poi, solo se serve, il proprio default interno.

Bootstrap, identità e contesto

Parametri che collegano il widget al backend o ne cambiano la modalità operativa.

data-api-url Richiesto

URL dell'API che alimenta il widget. In demo mode viene ignorato.

data-agent-id Richiesto

Agent ID usato per identificazione backend e chiamate API. In demo mode viene ignorato.

data-identity Default: null

Stringa o payload JSON con dati come name, email e phone, inviati al backend con un evento dedicato.

data-context Default: null

Contesto addizionale per l'assistente, utile per personalizzare la conversazione runtime.

data-cms Default: ''

Tipo di CMS (per esempio prestashop o woocommerce). Può abilitare varianti di feature come add to cart nei carousel prodotto.

data-is-demo Default: false

Attiva una conversazione demo con contenuto predefinito, disabilitando connessione reale e invio messaggi.

Quando vale true, API URL, agent ID e sessioni persistenti non vengono usati.

Copy, onboarding e contenuto della chat

Testi, suggerimenti iniziali e micro-copy mostrati all'utente.

data-title

Titolo del widget. Se assente, viene usato il titolo localizzato di default o quello remoto.

data-initial-message

Messaggio iniziale mostrato all'apertura. In demo mode è anche il primo messaggio della conversazione.

data-predefined-questions

Array JSON di domande cliccabili. Si mostra solo finché l'utente non invia il primo messaggio.

data-cta-text

Testo base del pulsante CTA sotto i messaggi. Può essere sovrascritto dal bot o dal contenuto demo.

data-footer-text

Testo personalizzato nel footer sotto il campo input. Se assente, usa il messaggio localizzato di default.

data-show-powered-by Default: true

Imposta false per nascondere la dicitura "Powered by Autocust" nel footer del widget.

Trigger, sessione e comportamento utente

Controlli per avvio chat, persistenza e interazioni iniziali.

data-button-icon Default: 💬

Icona del bottone flottante. Accetta testo, emoji, URL immagine o markup SVG.

data-button-overlay-text

Testo della bubble vicino al bottone su page load, pensata per attirare attenzione prima che svanisca.

data-button-overlay-delay Default: 5000

Durata in millisecondi della bubble di overlay prima del fade-out.

data-start-open Default: false

Se true il widget parte già aperto al caricamento della pagina.

data-persistent-session Default: false

Se true mantiene la cronologia tra sessioni e visite successive.

Ignorato in demo mode.

data-session-expiration Default: 24

Durata in ore della sessione persistente. Superato il TTL, la cronologia viene azzerata.

Ignorato in demo mode.

data-closable Default: true

Se false nasconde il pulsante di chiusura nell'header e impedisce di chiudere il widget una volta aperto.

Navigazione, layout e viewport

Gestione link, posizionamento e dimensioni del contenitore.

data-open-in-new-tab Default: true

Determina se i link generati dal widget vengono aperti in una nuova tab.

data-enable-utm Default: true

Se true aggiunge parametri UTM ai link prodotto. Imposta false per disabilitarli.

data-position Default: bottom-right

Posizione del widget tra top-left, top-right, bottom-left e bottom-right.

Ignorato se data-full-screen vale true.

data-full-screen Default: false

Se true il widget occupa tutto il viewport e ignora la posizione.

data-width Default: 340px

Larghezza del contenitore chat in modalità non fullscreen.

data-height Default: 485px

Altezza del contenitore chat in modalità non fullscreen.

data-z-index Default: 1000

Stacking order del widget non fullscreen rispetto agli altri layer della pagina.

Tema e palette

Override visivi per tema e singoli elementi del widget.

data-theme Default: light

Tema globale del widget: light oppure dark.

data-user-message-bg-color Default: #e0e0e0

Colore di sfondo dei messaggi utente.

data-user-message-text-color Default: #000000

Colore del testo nei messaggi utente.

data-assistant-message-bg-color Default: #f8f8f8

Colore di sfondo dei messaggi dell'assistente.

data-assistant-message-text-color Default: #000000

Colore del testo nei messaggi dell'assistente.

data-chat-button-bg-color Default: #000000

Colore di sfondo del bottone flottante di apertura.

data-chat-button-text-color Default: #ffffff

Colore del testo o icona nel bottone flottante.

data-cta-button-bg-color Default: #f8f8f8

Sfondo dei pulsanti CTA dentro la conversazione.

data-cta-button-text-color Default: #000000

Colore testo dei pulsanti CTA dentro la conversazione.

data-cta-button-hover-bg-color

Sfondo hover dei pulsanti CTA, con precedenza sul tema.

data-cta-button-hover-text-color

Colore testo hover dei pulsanti CTA, con precedenza sul tema.

data-header-bg-color

Colore di sfondo dell header del widget, sovrascrive il tema.

data-header-text-color

Colore testo di titolo e bottoni nell'header del widget.

Override avanzato

Ultimo livello di personalizzazione quando le opzioni standard non bastano.

data-custom-css Default: null

Stringa CSS grezza iniettata nello Shadow DOM del widget. Utile solo per styling avanzato e controllato.

Classi, id e markup interni non sono stabili: questo override può rompersi a ogni release e va testato.

Placement

Posizioni supportate

data-position accetta solo questi valori. Se il valore non è valido, il widget torna a bottom-right. In fullscreen la posizione viene ignorata.

top-left

Aggancia il widget nell'angolo superiore sinistro.

top-right

Aggancia il widget nell'angolo superiore destro.

bottom-left

Aggancia il widget nell'angolo inferiore sinistro.

bottom-right

Aggancia il widget nell'angolo inferiore destro. È il fallback di default.

JavaScript API

Controllo programmatico

Il widget espone window.autocustChatWidget e ascolta l'evento autocust:ask.

Apri il widget

Apre la chat programmaticamente, utile per CTA esterne o flussi custom.

window.autocustChatWidget.open()

Chiudi il widget

Chiude la chat. Se data-closable="false" la chiamata diventa un no-op.

window.autocustChatWidget.close()

Prefill della domanda

Inserisce il testo nel composer e, opzionalmente, lo invia subito.

window.autocustChatWidget.ask('Spedite all'estero?')
window.autocustChatWidget.ask('Spedite all'estero?', { sendImmediately: true })

window.dispatchEvent(
  new CustomEvent('autocust:ask', {
    detail: {
      question: 'Qual è la vostra policy resi?',
      sendImmediately: true,
    },
  })
)

Analytics

Eventi emessi dal widget

Tutti gli eventi sono CustomEvent emessi su window, con i dati in event.detail.

autocust:chatOpened

Scatta quando il widget viene aperto da click utente, API JS o apertura automatica.

Payload

Nessun payload obbligatorio: serve soprattutto per misurare engagement e trigger efficacy.

autocust:productClicked

Scatta quando un utente interagisce con un prodotto nel carousel, sia per view che per add to cart.

Payload

event.detail.product.id
event.detail.product.name
event.detail.product.price
event.detail.product.url
event.detail.action = 'view' oppure 'add_to_cart'

autocust:ctaClicked

Scatta quando un utente clicca un pulsante CTA sotto un messaggio.

Payload

event.detail.url
event.detail.ctaText

Tag Manager

Esempio GTM / dataLayer

Puoi intercettare gli eventi del widget e rilanciarli nel tuo stack analytics senza toccare il codice interno del componente.

window.addEventListener('autocust:chatOpened', () => {
  window.dataLayer = window.dataLayer || []
  window.dataLayer.push({ event: 'autocust_chat_opened' })
})

window.addEventListener('autocust:productClicked', (event) => {
  window.dataLayer = window.dataLayer || []
  window.dataLayer.push({
    event: 'autocust_product_clicked',
    product_id: event.detail.product.id,
    product_name: event.detail.product.name,
    interaction_type: event.detail.action,
  })
})

window.addEventListener('autocust:ctaClicked', (event) => {
  window.dataLayer = window.dataLayer || []
  window.dataLayer.push({
    event: 'autocust_cta_clicked',
    cta_text: event.detail.ctaText,
    destination_url: event.detail.url,
  })
})

Security

Content Security Policy

Se il sito usa CSP, abilita almeno i domini necessari per scaricare lo script e contattare l'API del tuo ambiente.

script-src: https://cdn.jsdelivr.net
connect-src: l'host passato in data-api-url

Advanced styling

Uso di data-custom-css

L'attributo data-custom-css inietta CSS nello Shadow DOM del widget. È potente, ma va trattato come escape hatch.

DOM interno, classi e id non sono un'API stabile e possono cambiare in ogni release.
Chi usa CSS custom deve ritestare il widget dopo ogni aggiornamento.
In produzione conviene pinare una versione testata dello script invece di usare sempre @latest.

Override inline

Configurazione remota

Default interni

Cosa è davvero obbligatorio

Installazione consigliata

Quando forzare opzioni locali

Attributi supportati

Bootstrap, identità e contesto

Copy, onboarding e contenuto della chat

Trigger, sessione e comportamento utente

Navigazione, layout e viewport

Tema e palette

Override avanzato

Posizioni supportate

Controllo programmatico

Eventi emessi dal widget

Esempio GTM / dataLayer

Content Security Policy

Uso di data-custom-css

Vuoi vederlo sul tuo sito?