Sito web

Ci sono tre modi per portare il tuo AI Agent Quickchat sul web. Scegli la forma più adatta:

• Widget: la bolla di chat mobile nell’angolo del sito. Ideale per l’assistenza generale.
• Embed: una finestra di chat integrata esattamente dove vuoi nella pagina. Ideale per una schermata dell’app, una pagina del centro assistenza o una scheda prodotto.
• Chat Page: una chat a schermo intero ospitata da Quickchat, senza installazione o codice. Ideale per condividere un link, per esempio via email di supporto, Slack interno o con beta tester, senza intervenire sul loro browser.

Installa la forma scelta da Channels → Your Website → Install. La pagina contiene tre sottoschede: Install per scegliere come aggiungere l’Agent, Appearance per lo stile visivo e Text Content per testi e etichette mostrati ai visitatori. Install si apre con la scelta del metodo, mantiene disponibilità e accessi in una sezione dedicata e mostra uno Scenario ID copiabile per plugin e API.

Strumenti di configurazione facoltativi

• Confronta i metodi di distribuzione. Confronta i canali, l’accesso al sito e le funzionalità richieste che hai indicato con le opzioni Quickchat AI. Lo strumento non esamina il tuo sito o account.

• Confronta HTML e Markdown di una pagina di esempio. Recupera HTML iniziale, contenuto Markdown e link agli strumenti da un esempio Quickchat AI predefinito. Non esegue JavaScript né esamina siti arbitrari.

Widget

Il Widget integra l’AI Agent direttamente nel sito, permettendo agli utenti di interagire facilmente con l’AI. Solitamente appare come una bolla nell’angolo in basso a destra. Facendo clic si apre una finestra in cui porre domande, ricevere assistenza o trovare informazioni.

Aggiungere il Widget al sito

Apri Channels → Your Website → Install. La scheda inizia con “How do you want to add your AI Agent?” ed elenca i metodi partendo dal più semplice. Scegli quello per il tuo sito:

• WordPress: installa il plugin gratuito Quickchat AI Agent, incolla lo Scenario ID e il Widget compare automaticamente, senza modificare il tema.
• Shopify: aggiungi il Widget tramite il Theme Editor del negozio. Vedi la guida Shopify.
• Webflow, Wix & others: copia uno snippet nell’impostazione di codice personalizzato per l’intero sito e applicalo a tutte le pagine. Non usare un elemento Embed o HTML su una pagina. Vedi Site builder.
• Share a link instead: non installare nulla; condividi il link della Chat Page ospitata.
• Install manually with code: copia lo snippet Widget o Embed e incollalo direttamente nell’HTML.

Ogni metodo apre un pannello con istruzioni mirate e solo il codice o l’ID necessario.

Lo Scenario ID è in cima alla scheda Install, in un campo copiabile. È l’identificativo richiesto da plugin e API: copialo da qui quando richiesto dalla configurazione.

Installazione manuale con codice

Se gestisci il tuo HTML, espandi Install manually with code nella scheda Install e:

1. Copia lo snippet Widget.
2. Apri il file HTML della pagina. Su un site builder usa invece l’impostazione per l’intero sito; vedi Site builder.
3. Incolla lo snippet subito prima del tag di chiusura </body> in ogni pagina in cui vuoi il Widget.

Controlla uno snippet Widget rispetto allo Scenario ID fornito. Il controllo legge il codice incollato, senza recuperare il sito.

Site builder

Su Webflow, Wix, Squarespace, Hostinger e strumenti simili, aggiungi il Widget una sola volta tramite il codice per l’intero sito:

1. Apri l’impostazione che aggiunge codice a tutte le pagine, solitamente Custom code, Code injection, Footer code o Body end.
2. Incolla lo snippet e applicalo a tutte le pagine. Se puoi scegliere la posizione, usa il footer o la fine del body. Lo snippet non funziona nell’head.
3. Pubblica il sito. La bolla di chat appare su ogni pagina.

Attenzione

Non aggiungere il Widget con un elemento Embed o HTML sulla pagina. Molti builder mostrano questi elementi in un piccolo frame separato, dove il Widget non può aprirsi. Anche se caricasse, apparirebbe solo su quella pagina.

Dove trovare l’impostazione per l’intero sito:

Builder	Impostazione del codice globale
Webflow	Site settings → Custom code → Footer code
Wix	Settings → Custom Code, poi All pages e Body - end. Richiede un dominio collegato.
Squarespace	Custom Code → Code Injection → Footer. Piani Core, Plus, Advanced e alcuni piani precedenti.
Hostinger Website Builder	More (⋯) → Integrations → Custom code. Gli script vengono caricati automaticamente a fine pagina.

I menu possono cambiare o essere tradotti nella lingua del builder. Se il builder o il piano non offre codice globale, condividi invece il link della Chat Page.

Ti serve una mano?

Non sei uno sviluppatore? La scheda Install offre due scorciatoie sotto Need a hand?:

• Ask AI for help: apre l’assistente nell’app con una domanda già compilata sull’aggiunta dell’Agent al sito.
• Email instructions to a developer: invia a un collega tutto il necessario, cioè snippet Widget, Scenario ID e link a questa guida, per installarlo al posto tuo.

Per altro aiuto, scrivi a contact@quickchat.ai.

Chat Page

La Chat Page è una versione ospitata, a schermo intero, dell’AI Agent su un URL Quickchat. Non richiede installazione: condividi il link e i visitatori possono chattare nel browser. Usala quando:

• Vuoi una chat ma non hai un sito o non vuoi modificarne il codice.
• Condividi l’AI con un piccolo gruppo, come beta tester, assistenza o potenziali clienti, e vuoi un link con accesso controllato anziché un widget pubblico.
• Vuoi inviare l’AI come canale di follow-up via email, Slack o CRM.

Configura chi può aprirla da Install → Chat Page Access. Vedi Controllo degli accessi.

Iniziare una nuova conversazione

Per ricominciare da zero:

• Widget o Embed: Apri la chat e fai clic sul pulsante con la penna in un quadrato in alto a destra.
• Chat Page: Seleziona New chat nella barra laterale o usa il pulsante con la penna nell’intestazione.

Si avvia una nuova conversazione con l’Agent. Quella precedente resta nell’Inbox. Chiudere e riaprire il Widget o ricaricare la pagina può riprendere la conversazione esistente. Chiedere all’AI di “resettare” o “cancellare la chat” non ne avvia una nuova. Non serve cancellare i cookie del browser.

Controllo degli accessi

La scheda Install raccoglie i controlli nella sezione espandibile Availability and access. Aprila per trovare due impostazioni:

Accesso a Widget ed Embed

L’interruttore in cima a Availability and access. Se attivo, gli script Widget ed Embed funzionano normalmente nei browser. Se disattivato, non sono disponibili sul sito anche se il codice è ancora presente. Utile per mettere temporaneamente offline l’AI senza rimuovere lo snippet o limitare l’accesso pubblico mantenendo la Chat Page per gli invitati.

Chat Page Access

Indipendentemente dall’interruttore Widget ed Embed, puoi limitare l’accesso alla Chat Page:

• Anyone: URL pubblico, utilizzabile da chiunque abbia il link.
• Invited users only: solo i Chat Users invitati via email possono usarla, dopo essersi autenticati.
• Nobody: Chat Page completamente disattivata.

Il link Invite Chat Users apre Settings → Organization → Team Members. Il modulo attuale offre ruoli del team con permessi dashboard; non fornisce un ruolo solo chat né una sezione Chat Users separata. Consulta Membri del team e ruoli prima di invitare qualcuno.

Personalizzazione

Le sottoschede Appearance e Text Content personalizzano l’aspetto di Widget, Embed e Chat Page e i testi visibili. Le tre forme condividono le impostazioni: modificale una volta per applicarle ovunque l’Agent sia distribuito.

Il pannello destro di Install/Appearance/Text Content ha controlli di anteprima: passa fra Widget, Embed e Chat Page, e fra Desktop e Mobile, per vedere le modifiche prima della pubblicazione.

Appearance

Lo stile visivo è organizzato in Branding, Size & Position, Theme e Other Settings.

Branding

• AI Agent Avatar: foto profilo o logo dell’Agent, una sola immagine usata nell’intestazione e sul pulsante di avvio, fino a 5 MB. È un’impostazione unica: carichi una volta e l’immagine appare in entrambi i punti, sostituendo i vecchi “header logo” e “launcher icon” separati. Ogni Agent parte con un avatar predefinito. Reset to default lo ripristina; eliminandolo non appare alcun avatar. Disponibile in tutti i piani, incluso Free.

AI Agent Avatar si applica a Widget, Embed e Chat Page, ma non a Discord, dove l’avatar proviene dall’app Discord del bot. Vedi Discord.

Size & Position

• Launcher size: Classic, Input Only o Small. Controlla l’aspetto del pulsante prima di aprire la chat.
• Chiusura del launcher: Classic ha un piccolo pulsante di chiusura in alto a destra, visibile al passaggio del mouse su desktop e sempre visibile sui dispositivi touch. Nasconde il widget solo per la visualizzazione corrente; torna al caricamento successivo. Le altre dimensioni non hanno il pulsante.
• Launcher label: appare solo con Small. Testo personalizzato sul pulsante piccolo, fino a 25 caratteri, per esempio “Ask AI” o “Chat”. Lascialo vuoto per mostrare solo l’icona.
• Widget position: in basso a sinistra, al centro o a destra.
• Dimensioni della finestra di chat: larghezza 300–700px e altezza 400–1200px.
• Draggable launcher: consente ai visitatori di trascinare il pulsante in un altro punto, utile se copre contenuti importanti.

Theme

Scegli i colori della chat:

• Light e Dark sono preset fissi uguali per tutti gli account.
• Custom offre una tavolozza completamente personalizzabile. Compaiono controlli per sfondo, intestazione e relativo testo, colore di accento usato per pulsante iniziale pre-chat, suggerimenti e valutazioni, bolle e testo dei messaggi, testo AI, colore dei link, campo di input, bordi e altro. Ogni colore viene controllato rispetto allo sfondo per il contrasto WCAG AA, con avvisi sulle combinazioni difficili da leggere.

I colori del brand per intestazione e accenti sono nel tema Custom. Light e Dark restano preset neutri: passando dall’uno all’altro non si trasferiscono colori personalizzati.

Sotto Transparency, Background determina quanto è trasparente la chat. Funziona con ogni tema, che fornisce la tinta:

• Solid: sfondo pieno, impostazione predefinita.
• Glass: finestra trasparente con il sito dietro sfocato, come vetro smerigliato. La tinta è bianca in Light, scura in Dark e corrisponde allo sfondo scelto in Custom. In Custom, un’intestazione di colore diverso conserva quel colore per mantenere il brand visibile. Glass opacity regola quanto la tinta copre la pagina, dal minimo che mantiene leggibile il testo su qualsiasi sito (50% in Light, 65% in Dark, in base ai colori in Custom) fino al 95%. Se nessun livello rende leggibile il testo con i colori Custom, il widget usa uno sfondo pieno e le impostazioni spiegano il motivo. Glass resta selezionato e torna applicabile dopo aver corretto colori del testo o dello sfondo per ottenere contrasto sufficiente.

La trasparenza si applica a Widget, anche sui telefoni, ed Embed. La Chat Page a pagina intera ha sempre sfondo pieno. Chi attiva “Reduce transparency” sul dispositivo vede Solid in Chrome ed Edge, i browser che comunicano questa preferenza ai siti. Se il browser non supporta la sfocatura, Glass resta quasi pieno per mantenere il testo leggibile.

Con Custom, la Chat Page ha anche colori propri per la barra laterale: Sidebar background, Sidebar text, Sidebar hover e Sidebar hover text. Valgono solo per la Chat Page completa, non per Widget o Embed. Lascia i colori del testo non impostati e verrà scelto automaticamente un colore leggibile sullo sfondo.

Puoi impostare anche il raggio degli angoli, che arrotonda bolle, campi e pulsanti, e la dimensione del testo. Entrambi valgono per ogni tema.

Other Settings

• Voice Input: permette di registrare un messaggio vocale dal microfono nella chat. Viene trascritto nel campo di input per modificarlo prima dell’invio. La registrazione termina dopo due minuti; disponibile nei piani a pagamento.
• File Attachments: permette di allegare immagini o documenti. Attivo per impostazione predefinita; disattivalo per rimuovere il pulsante allegati.
• Auto-open Widget: apre automaticamente il Widget al caricamento della pagina.
• Hide Quickchat AI Branding: nasconde il footer “Powered by Quickchat AI” per un’esperienza completamente white-label, nei piani che includono questa funzione.

Per consentire la valutazione delle conversazioni, apri Conversations → Insights → Conversation Rating. Impostazioni e risultati sono nella stessa scheda; vedi Valutazione delle conversazioni.

Text Content

Apri Channels → Your Website → Text Content per modificare il saluto e gli altri testi visibili:

• Header text: testo in cima alla finestra di chat.
• Welcome message: primo messaggio dell’Agent a ogni conversazione, per esempio “Ciao, ti serve aiuto?”.
• Show as a pop-up: mostra il benvenuto in una bolla accanto al launcher, spesso chiamata “teaser” o “launcher message”, per attirare l’attenzione prima del clic. La bolla usa proprio Welcome message, quindi modifica quel campo per cambiarne il testo.
• Conversation starters: fino a 3 messaggi d’esempio prima che il visitatore scriva. Il clic invia il testo come primo messaggio, utile per indirizzare verso i punti di forza dell’AI, come “Come installo il widget?” o “Quali integrazioni supportate?”.
• Input placeholder: suggerimento nel campo messaggio vuoto.
• Disclaimer text: testo dietro la conversazione, solitamente per informare che si sta parlando con un’AI. Consigliamo di mantenerlo chiaro e visibile.

La sezione Pre-chat Screen è sotto questi campi nella stessa scheda Text Content. Attivala lì e modifica intestazione, pulsante e messaggio.

Lingue e traduzioni

Per impostazione predefinita, tutti vedono Text Content esattamente come lo hai scritto. Nei piani a pagamento puoi aggiungere traduzioni per lingua, così i visitatori vedono il widget nella propria lingua.

1. Apri Text Content e fai clic su Translate in Other languages. Si apre Translate widget text, con il testo principale accanto alle traduzioni come Default (source).
2. Fai clic su Add language e scegli una lingua. Quickchat AI traduce il testo attuale. Controlla e modifica intestazione, benvenuto, spunti di conversazione, placeholder, schermata pre-chat e disclaimer. Le modifiche si salvano automaticamente.
3. I campi lasciati vuoti usano il testo predefinito, così traduci solo ciò che vuoi cambiare. Se la traduzione automatica fallisce, puoi inserire il testo manualmente.

Il numero di lingue aggiungibili dipende dal piano.

Come viene scelta la lingua del visitatore

Per Widget ed Embed, Quickchat segue questo ordine:

1. Un override esplicito nel loader: _quickchat("language", "de"), da chiamare prima di _quickchat("init", ...).
2. L’attributo <html lang> della pagina: per esempio <html lang="de"> mostra la traduzione tedesca. È il metodo consigliato: imposta correttamente lang su ogni pagina localizzata e il widget si adatta automaticamente.
3. La lingua del browser, poi il testo Default se non c’è corrispondenza.

Nota

Se manca una traduzione nella lingua del visitatore, viene sempre mostrato Default. Nessun campo resta vuoto.

Funzioni avanzate: parametri personalizzati

Widget ed Embed permettono di passare parametri personalizzati all’inizializzazione. Possono:

• migliorare le analisi, essendo disponibili nell’esportazione CSV della piattaforma
• fornire valori alle API Actions e, dove consentito, personalizzare le risposte. L’AI riceve solo un sottoinsieme filtrato; vedi Contesto del modello e autorizzazione

Esempi di parametri utili:

• visitor_name: Mike
• customer_tier: VIP
• order_id: ord_123

visitor_name è una chiave di contatto riconosciuta. Chiavi come customer_tier possono essere salvate e usate nelle Actions, ma inviarle non garantisce che l’AI le usi nelle risposte. Considera i valori del browser come input non verificati, non come autorizzazione ad accedere all’account di un cliente.

Per aggiungere questi parametri, includi quanto segue nello script trovato in Your Website > Install.

Widget ed Embed usano la stessa forma di chiamata:

_quickchat("custom_params", {
  "visitor_name": "Mike",
  "customer_tier": "VIP",
  "order_id": "ord_123",
});

Gli attributi vengono assegnati a ogni nuova conversazione; consigliamo di limitarsi a poche chiavi.

Consiglio

Parametri con nomi snake_case, come order_id o customer_tier, possono essere inseriti direttamente nelle API Actions come {{metadata_order_id}}, {{metadata_customer_tier}} e così via. Vedi Variabili AI Action.

Script di esempio:

widget

<script>
  (function(e,a,d,i,c,t=a.createElement(d)){e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},t.src=i,t.async=1,a.body.insertAdjacentElement("beforeend",t)})(window,document,"script","https://bubble.quickchat.ai/chat.js","_quickchat");
  _quickchat("custom_params", {"visitor_name": "Mike", "customer_tier": "VIP", "order_id": "ord_123"});
  _quickchat("init", "abcdefghij");
</script>

Embed

<div id="quickchat-embedded" style="height:600px;overflow:hidden;"></div>
<script>
  (function(e,a,d,i,c,t=a.createElement(d)){e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},t.src=i,t.async=1,a.body.insertAdjacentElement("beforeend",t)})(window,document,"script","https://bubble.quickchat.ai/chat.js","_quickchat");
  _quickchat("containerId", "quickchat-embedded");
  _quickchat("custom_params", {"visitor_name": "Mike", "customer_tier": "VIP", "order_id": "ord_123"});
  _quickchat("init", "abcdefghij");
</script>

Embed

Embed posiziona l’AI Agent nella pagina come finestra di chat integrata, anziché come bolla mobile. Usalo per collocarla in un punto preciso, come una colonna del centro assistenza, una pagina contatti o una barra laterale nell’app.

Aggiungere l’Embed

1. Recupera il codice Embed

   • Accedi alla Quickchat AI App.
   • Vai in Channels → Your Website nella barra laterale sinistra.
   • Apri Install, poi espandi Install manually with code.
   • Copia lo snippet Embed, che include contenitore <div id="quickchat-embedded"> e script di caricamento.

2. Apri il file HTML del sito o la pagina nel builder.

3. Incolla il codice

   • Inserisci lo snippet Embed nel <body> della pagina.
   • Posizionalo esattamente dove vuoi la chat. Il <div> controlla le dimensioni: adatta style="height:600px" allo spazio del layout.
   • Nel builder aggiungi un elemento codice o HTML nel punto desiderato e incolla lo snippet al suo interno.

Nota

Embed funziona solo se il builder inserisce il codice direttamente nella pagina. Alcuni, per esempio Wix, mostrano gli elementi HTML in un frame separato, dove Embed non può caricarsi. Se la chat non appare nella pagina pubblicata, aggiungi il Widget con il codice globale o condividi la Chat Page.