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 |
| OpenRouter | GPT-oss-120B:free, Trinity:free, GLM-4.5-air:free | 3 modelli gratuiti con fallback |
Piani disponibili
| Caratteristica | Free | Pro (29€/mese) | Ultra (99€/mese) |
|---|---|---|---|
| Assistenti | 1 | 5 | Illimitati |
| Crediti/mese | 25.000 | 400.000 | 3.000.000 |
| Messaggi/giorno | 50 | 2.000 | 20.000 |
| AI Actions & Webhook | — | ✅ | ✅ |
| Lead Capture | — | ✅ | ✅ |
| Human Handoff | — | ✅ | ✅ |
| 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
CTA "Crea il tuo Assistente Gratis"
80% riduzione costi, 24/7, <2s risposta
Tutte le funzionalità principali
4 step: Carica → Configura → Integra → Analizza
Free / Pro / Ultra con toggle annuale
Invita un amico → 50.000 crediti gratis
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
Crediti
400K
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
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>
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
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, crediti in esaurimento, handoff in attesa, report settimanale
20. Billing e Crediti
| Pacchetto | Prezzo |
|---|---|
| 100.000 crediti | 9,99€ |
| 500.000 crediti | 39,99€ |
| 2.000.000 crediti | 99,99€ |
Come funzionano: 1 credito ≈ 1 token. Ogni messaggio consuma: System Prompt + KB + FAQ + History + Risposta.
Referral: Invita amici → 50.000 crediti 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)
Conformità GDPR
- Consenso preventivo
- Informativa privacy nel widget
- Diritto alla cancellazione
- Diritto all'export dati
- DPA disponibile (Ultra)
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 crediti 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 "Richiedi consenso" sia attivato
- 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)
© 2026 SmartChatAssistant — by Gabriele Ferrari
Hai bisogno di aiuto? supporto@smartchatassistant.com