Guida Utente Completa
Tutto quello che devi sapere per creare, configurare e ottimizzare il tuo assistente AI con SmartChatAssistant.
Versione 1.0 · Ultimo aggiornamento: Marzo 2026
1. Panoramica della Piattaforma
SmartChatAssistant è una piattaforma SaaS che permette di creare assistenti virtuali AI personalizzati, addestrati sui dati del proprio business, da integrare su qualsiasi sito web tramite un semplice snippet JavaScript.
↕
Dashboard di gestione
Provider AI supportati
| Provider | Modelli | Note |
|---|---|---|
| OpenAI | GPT-4o, GPT-4o-mini | Richiede API key |
| Google Gemini | Gemini Pro, Gemini Flash | Richiede API key |
| Anthropic (Claude) | Claude Haiku 5.5 (predefinito), Sonnet 5.5, Opus 5.5 | Richiede API key |
| OpenRouter | Solo modelli gratuiti (es. Gemma 4 31B, Nemotron), lista aggiornata ogni giorno | Gratuiti, con fallback automatico |
Piani disponibili
| Caratteristica | Free | Pro (29€/mese) | Ultra (99€/mese) |
|---|---|---|---|
| Assistenti | 1 | 5 | Illimitati |
| Messaggi AI/mese | 100 | 4.000 (~800 conversazioni) | 15.000 (~3.000 conversazioni) |
| Messaggi/giorno per assistente | 50 | 2.000 | 20.000 |
| AI Actions & Webhook | — | ✅ | ✅ |
| Lead Capture | — | ✅ | ✅ |
| Human Handoff | — | ✅ | ✅ |
| Aggiornamento automatico pagine web (KB) | Solo manuale | Ogni 7 giorni | Ogni giorno |
| Membri team | 1 | 5 | 20 |
| CSS personalizzato | ✅ | ✅ | ✅ |
2. Area Pubblica (Landing Page)
La landing page è la vetrina della piattaforma, accessibile a chiunque senza login.
Dettaglio sezioni
Hero section
Feature cards
Piani e prezzi
Footer
Sezioni della landing page
"L'assistente AI che non solo risponde: vende", chat di esempio con schede prodotto, CTA "Crea il tuo Assistente Gratis"
WooCommerce, WordPress, Shopify, Wix, OpenAI, Gemini
Sezione dedicata al catalogo WooCommerce: plugin gratuito, consigli solo su prodotti reali, schede in chat, click tracciati
80% riduzione costi, 24/7, <2s risposta
Tutte le funzionalità principali
4 step: Carica → Configura → Integra → Analizza
Free / Pro / Ultra in messaggi AI, toggle annuale, nota su modelli standard e premium
Invita un amico → 200 messaggi AI gratis
Privacy, Termini, Cookie e la pagina pubblica Sicurezza e GDPR
3. Registrazione e Accesso
Registrazione
- Clicca "Inizia Gratis" o "Registrati"
- Compila: Nome, Email, Password
- Conferma la registrazione
- Verifica l'indirizzo email (banner giallo nella dashboard)
Login
- Email + Password — form classico con protezione anti brute-force
- Google OAuth — login rapido con un click
Login con credenziali compilate:
Sicurezza: Protezione CSRF, rate limiting, cookie httponly+samesite, sessione con scadenza automatica (1h inattività).
4. Dashboard Principale
Card metriche
Assistenti
N
Piano
Pro
Messaggi AI
4.000
Utilizzo
30%
Sidebar di navigazione
Globale
Dashboard, Assistenti
Assistente
Impostazioni, KB, FAQ, Actions, Lead, Widget, Welcome Rules, Webhook, Conversazioni, Playground, Analytics, Handoff
Account
Admin, Account, Team, Billing, Logout
5. Gestione Assistenti
Creare un nuovo assistente
- Vai su Assistenti → Nuovo Assistente
- Compila: Nome, Provider AI, Modello AI
- Opzionale: usa il Wizard Prompt per generare il system prompt
- Clicca Crea
Wizard AI per la generazione del prompt:
Configurare un assistente
Dalla pagina Impostazioni puoi modificare:
- Generale: Nome, API Key (copia con un click)
- System Prompt: Personalità, tono, competenze, limiti + indicatore token
- Modello AI: Provider, Modello, Max Context Tokens, Max History, BYOK, Fallback. Con BYOK (la tua API key) ogni risposta conta sempre 1 messaggio AI, qualunque modello e lunghezza.
Barra Utilizzo Contesto: [System Prompt] + [FAQ] + [KB] + [History] + [Risposta] = Totale token. Verde <70%, Ambra 70-90%, Rosso >90%.
Codice di incorporamento
data-api-key="LA_TUA_API_KEY"
defer></script>
Chat in pagina (iframe): per avere la chat sempre aperta dentro una pagina del sito (es. "Assistenza") invece della bolla in basso, usa la scheda In pagina (iframe) e incolla il codice dove vuoi la chat. Larghezza e altezza le decidi tu; si può usare insieme alla bolla.
style="width:100%;max-width:720px;height:600px;border:none;"
title="Chat" allow="microphone; clipboard-write" referrerpolicy="no-referrer-when-downgrade"></iframe>
6. Knowledge Base
La Knowledge Base è il "cervello" dell'assistente: le informazioni che usa per rispondere.
4 modalità di importazione
Titolo + contenuto testuale. Ideale per descrizioni prodotti, regolamenti.
PDF, TXT, DOCX, CSV (max 10 MB). Testo estratto automaticamente.
Inserisci un URL, il sistema scarica e analizza il contenuto.
URL di partenza, profondità 1-3, max 1-20 pagine. Importa l'intero sito.
Esempio: modalità Crawl automatico
Aggiornamento automatico: le pagine importate da URL o tramite crawl vengono riscansionate automaticamente (Pro ogni 7 giorni, Ultra ogni giorno; Free solo manualmente). Vengono sostituite solo le pagine il cui contenuto è cambiato; uno snippet modificato a mano è escluso dall'aggiornamento automatico.
Consiglio: Se il contesto è vicino al limite, disattiva gli snippet meno importanti anziché eliminarli.
7. FAQ Strutturate
Coppie domanda/risposta con priorità massima nel contesto dell'assistente.
Creare una FAQ
- Domanda principale — Es. "Quali sono gli orari di apertura?"
- Varianti — Formulazioni alternative ("A che ora aprite?", "Siete aperti il sabato?")
- Risposta — La risposta esatta che l'AI deve fornire
- Ordine — 1-100 (più basso = più prioritario)
Form di creazione FAQ:
Best practice: Aggiungi almeno 2-3 varianti per ogni FAQ per migliorare il riconoscimento.
8. AI Actions
Permettono all'assistente di agire, non solo rispondere. Piano Pro+
L'AI richiede nome, email, telefono e salva automaticamente.
Mostra un pulsante cliccabile con URL di destinazione.
Invia email di notifica a un indirizzo specifico.
Chiama endpoint esterno con parametri e usa la risposta.
Form di creazione azione:
Gestire le azioni esistenti
Ogni azione in elenco ha tre controlli: ON/OFF per attivarla o sospenderla, la matita per modificarla e il cestino per eliminarla. La matita riapre il modulo già compilato, così puoi correggere nome, istruzione e configurazione (destinatario, URL del bottone, endpoint) senza ricreare l'azione da zero. Il tipo, invece, non è modificabile.
Notifica Email — destinatari multipli e trascrizione. Nel campo destinatario puoi indicare fino a 5 indirizzi separati da virgola: ognuno riceve la propria copia. L'email contiene il motivo della notifica e la trascrizione della conversazione, quindi funziona bene come riepilogo di fine sessione.
Più azioni nella stessa risposta. L'assistente può richiamare più azioni insieme (ad esempio raccolta lead e notifica email in chiusura) e vengono eseguite tutte. Nel Playground le azioni sono simulate: l'email non viene spedita davvero, serve il widget reale per la prova completa.
9. Gestione Lead
Raccoglie tutti i contatti catturati durante le conversazioni. Piano Pro+
Ogni lead: nome, email, telefono, stato, data. Puoi cambiare stato, aggiungere note, esportare in CSV.
Campi del form lead
Nella pagina Lead, il pannello «Campi del form lead» decide che cosa viene chiesto al visitatore:
- Campi standard — Nome, Email, Telefono, Azienda, Messaggio: si attivano singolarmente e ognuno ha l'opzione «Obbligatorio».
- Campi personalizzati — fino a 5, separati da virgola (es.
Marca auto, Anno immatricolazione). L'etichetta che scrivi è quella mostrata nel widget ed è anche il nome con cui il valore compare nel dettaglio del lead, nell'email e nell'export CSV. Per il visitatore sono sempre facoltativi.
Le modifiche valgono dal caricamento successivo del widget: ricarica la pagina che lo ospita per vederle.
Dove arrivano i lead. Ogni lead genera un'email con i dati raccolti e la trascrizione della chat. Di default arriva all'indirizzo del tuo account; per riceverla altrove apri AI Actions → Raccolta Lead → matita e indica uno o più destinatari (max 5, separati da virgola).
10. Impostazioni Widget
🎨 Colori (6 indipendenti)
✏️ Aspetto
💬 Messaggi
⚙️ Comportamento
🔒 GDPR & Sicurezza
🎨 CSS personalizzato
Il tuo CSS viene applicato nel widget dopo gli stili base, quindi li sovrascrive senza bisogno di !important. Resta confinato al widget: non può alterare il sito che lo ospita.
Selettori disponibili: #sca-container (con le varianti .sca-bottom-right e .sca-bottom-left), #sca-toggle per il pulsante, #sca-window per la finestra di chat.
/* pulsante e finestra a 100px dal fondo */
#sca-container.sca-bottom-right,
#sca-container.sca-bottom-left { bottom: 100px; }Massimo 10.000 caratteri. Non sono ammessi @import, javascript: e i tag <script> / </style>: il salvataggio viene rifiutato con un messaggio che indica la sequenza da rimuovere. Le modifiche si vedono al ricaricamento della pagina che ospita il widget.
11. Welcome Rules
Messaggi di benvenuto diversi in base alla pagina che il visitatore sta navigando.
| URL contiene | Messaggio | Suggerimenti |
|---|---|---|
| /prezzi | Hai domande sui nostri piani? | Confronta i piani, Quanto costa? |
| /prodotto/ | Vuoi saperne di più su questo prodotto? | Caratteristiche, Disponibilità |
| /contatti | Posso aiutarti a trovare il contatto giusto? | Assistenza tecnica, Commerciale |
Form creazione regola:
12. Template Library
Modelli pronti all'uso per diversi settori verticali: prompt, FAQ e welcome rules ottimizzati.
Settori disponibili
System Prompt del template
FAQ incluse nel template
Come usare un template
- Vai nella sidebar → Template Library
- Sfoglia i settori e clicca su quello che ti interessa
- Visualizza: System Prompt, FAQ e Welcome Rules
- Seleziona con checkbox cosa importare
- Clicca Applica Template
Best practice: Usa il template come punto di partenza, poi personalizza ogni elemento con i dati reali del tuo business.
13. Webhook
Inviano notifiche in tempo reale verso sistemi esterni. Piano Pro+
Automazioni no-code
Salesforce, HubSpot
Notifiche canale
Log conversazioni
14. Conversazioni
Storico completo delle chat: Session ID, date, numero messaggi, URL provenienza.
Dettaglio di una conversazione:
Best practice: Controlla periodicamente le conversazioni per identificare domande ricorrenti → crea nuove FAQ o arricchisci la KB.
15. Playground
Ambiente di test isolato per provare l'assistente prima di metterlo live.
Esempio di conversazione nel Playground:
Best practice: Dopo ogni modifica a KB, FAQ o prompt, testa sempre nel Playground prima di andare live.
16. Analytics
Metriche dettagliate sulle performance. Periodo: 7, 30 o 90 giorni. Grafici avanzati: Pro+
Sessioni uniche
Totale scambiati
Latenza media ms
% thumbs up
Ora più attiva
6 Grafici interattivi
- Conversazioni per giorno (Line chart)
- Tempo di risposta medio (Line chart)
- Soddisfazione nel tempo (Trend)
- Attività per ora (Bar chart 24h)
- Token consumati (Stacked bar)
- Funnel conversione lead (Horizontal bar)
17. Human Handoff
Quando l'AI non riesce, il visitatore chiede un operatore umano. Piano Pro+
Lato Visitatore
Pulsante "Parla con operatore" → richiesta handoff → messaggio di attesa
Lato Operatore
Badge con richieste in attesa → leggi conversazione AI → rispondi → risolvi
18. Team Multi-utente
| Ruolo | Permessi |
|---|---|
| Admin | Accesso completo, gestione team, billing |
| Editor | Crea/modifica assistenti, KB, FAQ, azioni |
| Viewer | Solo visualizzazione |
Free: 1 membro · Pro: 5 · Ultra: 20
19. Account e Notifiche
Profilo
Modifica nome, email, password
Notifiche email
Nuovo lead, messaggi AI in esaurimento, handoff in attesa, report settimanale
20. Billing e Messaggi AI
| Pacchetto | Prezzo |
|---|---|
| 1.000 messaggi AI | 9,99€ |
| 5.000 messaggi AI | 39,99€ |
| 15.000 messaggi AI | 99,99€ |
Come funzionano: 1 credito = 1 messaggio AI = una risposta generata dall'AI su un modello standard (gpt-4.1-nano, gpt-4o-mini, gpt-4.1-mini, gemini-2.5-flash-lite, gemini-3.1-flash-lite, gemini-2.5-flash, gemini-3-flash-preview, claude-haiku-5-5, modelli gratuiti OpenRouter). I modelli premium (GPT-4o, GPT-4.1, modelli Gemini Pro, gemini-3.5-flash, Claude Sonnet 5.5 e Opus 5.5, qualsiasi modello OpenRouter a pagamento o ID modello personalizzato) contano 5 messaggi AI per risposta.
Risposte lunghe: se contesto + risposta superano 8.000 token, si conta uno scaglione in più ogni 8.000 token (es. 12.000 token = 2 messaggi AI su un modello standard, 10 su un modello premium).
BYOK: se l'assistente usa la tua API key, ogni risposta conta 1 messaggio AI, senza moltiplicatori per modello o lunghezza.
Referral: Invita amici → 200 messaggi AI gratis per entrambi. Nessun limite inviti.
21. Export / Import Assistenti
Pulsante Export nella lista assistenti
Form di Import assistente
Export
Scarica pacchetto JSON completo: configurazione, KB, FAQ, Actions, Widget Settings, Welcome Rules.
Import
Carica un JSON esportato → nuovo assistente con tutta la configurazione.
22. Integrazione nel Sito
data-api-key="LA_TUA_API_KEY"
defer></script>
Come funziona
- Lo script carica la configurazione dall'API
- Mostra il bubble nell'angolo configurato
- Al click, apre la finestra chat
- Se richiesto, mostra il banner GDPR
- Messaggi inviati → API → AI risponde
- Sessione persistente per la durata configurata
Multi-lingua: Il widget rileva la lingua del browser e risponde automaticamente nella stessa lingua (15+ lingue).
23. Sicurezza e GDPR
Sicurezza
- Crittografia dati sensibili
- CSRF Protection
- Rate Limiting
- Content Security Policy
- HTTPS forzato
- IP hashati (SHA-256)
- Autenticazione a due fattori (2FA)
- Dati dei lead cifrati con AES-256
- Server in Italia (UE)
Conformità GDPR
- Consenso preventivo
- Informativa privacy nel widget
- Diritto alla cancellazione
- Diritto all'export dati
- Anonimizzazione conversazioni: 30 giorni (Free), 90 (Pro), 365 (Ultra)
- Nessun addestramento dei modelli OpenAI/Gemini sui tuoi contenuti
- DPA su richiesta (Pro e Ultra)
Pagina pubblica Sicurezza e GDPR: da girare ai tuoi clienti. Spiega ruoli (tu titolare, SmartChatAssistant responsabile ex art. 28), percorso dei dati, sub-responsabili, addestramento dei modelli (eccezione: i modelli free di OpenRouter possono registrare i prompt) e come richiedere il DPA: email a privacy@smartchatassistant.com dall'indirizzo dell'account, con ragione sociale, P.IVA e referente privacy.
24. Pannello Admin
Accessibile solo agli utenti con ruolo amministratore di piattaforma.
- Lista Utenti — tutti gli utenti registrati
- Assistenti per Utente — vedi assistenti di un utente specifico
25. Best Practice
System Prompt
✅ Definisci chiaramente il ruolo
✅ Specifica il tono (formale, informale, tecnico)
✅ Elenca gli argomenti di cui può parlare
✅ Definisci i limiti ("Non inventare informazioni")
✅ Indica come gestire le domande fuori tema
✅ Aggiungi istruzioni per la raccolta lead
Knowledge Base
✅ Mantieni gli snippet aggiornati
✅ Usa titoli descrittivi
✅ Disattiva (non eliminare) snippet temporanei
✅ Monitora la barra contesto — non superare l'80%
FAQ
✅ Almeno 3 varianti per domanda
✅ Risposte concise e precise
✅ Ordini bassi (10-20) per FAQ critiche
Widget
✅ Colori coerenti col brand
✅ Messaggio di benvenuto coinvolgente
✅ 2-4 messaggi suggeriti
✅ Abilita consenso GDPR
✅ Testa su mobile
Monitoraggio
✅ Controlla settimanalmente "Domande Senza Risposta"
✅ Monitora la soddisfazione — sotto il 70% rivedi prompt e KB
✅ Analizza il funnel lead
✅ Verifica il tempo di risposta — se >5s, modello più veloce
26. Checklist — Da Zero a Live
Fase 1 — Setup
Fase 2 — Creazione assistente
Fase 3 — Addestramento
Fase 4 — Widget
Fase 5 — Go Live
27. Risoluzione Problemi
Il widget non appare sul sito
- Verifica che lo snippet sia nel
<head>della pagina - Controlla che l'API key sia corretta
- Verifica i domini autorizzati (o lascia vuoto per accettare tutti)
- Apri la console browser (F12) e cerca errori JavaScript
- Verifica che l'assistente sia attivo
L'assistente non risponde
- Verifica di avere messaggi AI sufficienti
- Controlla la configurazione del provider AI
- Se usi BYOK, verifica che la API key sia valida
- Controlla i log per errori di connessione
Le risposte sono imprecise
- Rivedi il system prompt — è abbastanza specifico?
- Aggiungi FAQ per le domande problematiche
- Verifica che la KB sia corretta e aggiornata
- Controlla la barra contesto — se 100%, possibile troncamento
Il consenso GDPR non appare
- Verifica che "Informativa privacy nella chat" non sia impostata su Nessuno
- Con l'Avviso, se il visitatore l'ha già chiuso con la X non viene più mostrato su quel browser
- Controlla che il messaggio consenso non sia vuoto
I lead non vengono catturati
- Verifica che l'action "Raccolta Lead" sia attiva
- Controlla il system prompt per istruzioni di raccolta dati
- Verifica di avere un piano che supporta lead (Pro o Ultra)
28. Catalogo WooCommerce
Dal piano Pro (fino a 2.000 prodotti; Ultra 20.000). L'assistente consiglia i prodotti del tuo negozio WooCommerce in base all'esigenza del visitatore e li mostra come schede cliccabili (immagine, nome, prezzo, attributi) che portano alla pagina prodotto del tuo sito. Nessuna configurazione di settore: ciò che distingue una parafarmacia da un negozio di abbigliamento sono i tuoi dati e le istruzioni che scrivi.
Come funziona
- Installi il plugin SCA Connector for WooCommerce sul sito WordPress: genera il feed del catalogo e lo rigenera a intervalli in background.
- SmartChatAssistant legge il feed (1 h di default, completo una volta al giorno). Il sito non invia nulla.
- Da ogni lettura nasce uno schema del catalogo (categorie, attributi con i valori più frequenti, prezzi) che entra nel prompt: così l'AI capisce da sola il tuo settore.
- In chat l'assistente cerca nel catalogo (testo, categoria, prezzo, disponibilità, attributi), anche più volte nello stesso turno, propone da 1 a pochi prodotti, chiede chiarimenti se l'esigenza è vaga e non propone mai prodotti esauriti.
Configurazione
- Plugin (WooCommerce → SCA Connector): URL del feed e token da copiare, intervallo di rigenerazione (15 min – 24 h o personalizzato), rigenerazione al salvataggio di un prodotto, meta field extra da esportare, anteprima, stato dell'ultima rigenerazione, "Rigenera ora", ultima lettura da SmartChatAssistant.
- Dashboard (assistente → Catalogo): URL e token, "Test connessione", intervallo di lettura, modalità di ricerca, max prodotti per risposta, istruzioni di consulenza (cosa chiedere e cosa evitare nel tuo settore), attributi da mostrare nelle schede (max 3), parametri UTM, interruttore, "Sincronizza ora" e stato.
- Widget: carosello di schede sotto la risposta, click in nuova scheda, evento JavaScript
sca:product_clickper Google Tag Manager.
Suggerimento: nel Playground con il debug acceso la sezione "Catalogo WooCommerce" mostra le ricerche fatte dal modello e i prodotti selezionati: usala per mettere a punto le istruzioni di consulenza.
29. Collegare Claude (connettore MCP)
Dal piano Pro. Puoi collegare Claude.ai, Claude Cowork e Claude Code al tuo account: Claude legge assistenti, knowledge base, FAQ, conversazioni, lead e analytics, prova le risposte dell'assistente e, se lo autorizzi in scrittura, modifica prompt, FAQ, knowledge, widget e risponde agli handoff. Tutto quello che Claude fa passa dagli stessi controlli della dashboard e resta registrato in Account → Claude / MCP.
Claude.ai e Claude Cowork
- Su claude.ai apri Impostazioni → Connettori (in Cowork: Connettori) e scegli Aggiungi connettore personalizzato.
- Nome:
SmartChatAssistant. URL:https://app.smartchatassistant.com/mcp. Lascia vuoti client ID e secret. - Clicca Connetti: si apre la pagina di autorizzazione di SmartChatAssistant (se non sei loggato, prima il login).
- Scegli il livello di accesso (sola lettura o lettura e scrittura) e quali assistenti condividere, poi Autorizza.
- In una chat con Claude attiva il connettore e chiedi ad esempio: "Elenca i miei assistenti", "Riassumi le conversazioni dell'ultima settimana dell'assistente X", "Proponi 10 FAQ dalle domande senza risposta".
Claude Code
- In Account → Claude / MCP crea un token personale (nome, livello di accesso, assistenti) e copialo subito: non viene più mostrato.
- Nel terminale esegui:
claude mcp add --transport http smartchatassistant https://app.smartchatassistant.com/mcp --header "Authorization: Bearer IL_TUO_TOKEN"In alternativa, senza token: claude mcp add --transport http smartchatassistant https://app.smartchatassistant.com/mcp e poi /mcp dentro Claude Code per autenticarti con la stessa pagina di autorizzazione di Claude.ai.
Cosa può fare Claude
In sola lettura
Vedere configurazione, knowledge, FAQ, azioni, widget, conversazioni, domande senza risposta, lead, handoff, analytics, catalogo. Fare domande all'assistente come un visitatore (consuma messaggi AI come il widget) e vedere il prompt esatto che riceve il modello.
In lettura e scrittura
In più: creare nuovi assistenti (entro il limite del piano), modificare nome, prompt e modello, aggiungere/modificare/eliminare knowledge e FAQ, importare una pagina web, aggiornare i testi del widget, cambiare stato e note dei lead, rispondere e chiudere gli handoff. Le eliminazioni richiedono sempre una conferma esplicita.
Sicurezza
- Claude vede solo i tuoi assistenti (e solo quelli scelti al momento dell'autorizzazione).
- Ogni connessione si revoca con un clic in Account → Claude / MCP, dove trovi anche l'elenco delle ultime chiamate.
- Le chiavi API dei provider e i segreti delle azioni non vengono mai esposti.
- Limite di 60 chiamate al minuto per connessione (di più nei piani superiori).
© 2026 SmartChatAssistant — by Gabriele Ferrari
Hai bisogno di aiuto? supporto@smartchatassistant.com