Chatbot Builder - Guida
Guida completa per creare chatbot AI da vari documenti e fonti web
Panoramica
Chatbot Builder (Chatbotty.ai) è una piattaforma ottimizzata con Redis Cache per la creazione di chatbot AI da vari documenti e fonti web. È pensata per chiunque abbia bisogno di fornire risposte di qualità alle domande degli utenti basandosi su documenti e fonti aggiornati - uffici pubblici, organizzazioni, aziende e privati.
✨ Funzionalità principali
🤖 AI ed elaborazione
- • Chatbot AI da vari documenti e fonti web
- • Routing AI intelligente per qualità ottimale delle risposte
- • Database vettoriale per la ricerca semantica
- • Suddivisione avanzata per tipo di documento
⚡ Prestazioni e affidabilità
- • Cache multilivello (Memory → Redis → PostgreSQL)
- • Widget asincrono senza impatto sulla velocità della pagina
- • Protezione contro abusi e attacchi bot
- • Limiti di velocità flessibili per singoli chatbot
📊 Gestione e analytics
- • Ampie opzioni di personalizzazione e configurazione
- • Sostituzione automatica dei documenti con nuove versioni
- • Analytics in tempo reale e ottimizzazione della qualità
- • Gestione automatica di abbonamenti e piani
🎯 Ideale per
- Uffici pubblici e istituzioni
Automazione dei servizi informativi per i cittadini, risposte alle domande frequenti sulle procedure ufficiali
- E-commerce e servizi online
Assistenza clienti intelligente senza call center, gestione di ordini e reclami
- Aziende con documentazione estesa
Ricerca rapida nelle risorse interne, onboarding di nuovi dipendenti
- Istituti educativi
Supporto agli studenti e risposte alle domande frequenti, informazioni sui programmi di studio
- Strutture sanitarie
Informazioni ai pazienti e supporto amministrativo, guide per i pazienti
- Studi legali
Accesso rapido a documenti legali e precedenti, analisi di casi giuridici
- Aziende IT e tecnologiche
Automazione del supporto tecnico e documentazione API, risoluzione di problemi comuni
- Società di consulenza
Condivisione di competenze e best practice, knowledge base interna
- Agenzie di marketing
Analisi delle esigenze dei clienti e ottimizzazione dei contenuti, supporto ai brief creativi
Per iniziare
🎯 Guida rapida
- 1Registrazione e accesso
Crea il tuo account. Ricevi automaticamente il piano Evaluation per 14 giorni con 3.000 messaggi/mese (più dei 500 del piano Elite) e tutte le funzionalità Elite.
- 2Creazione del primo chatbot
Clicca su "Nuovo Chatbot" → inserisci nome e descrizione → scegli lo stile di risposta (formale/amichevole/professionale). Dopo la creazione, verrai reindirizzato alle impostazioni dettagliate dove puoi personalizzare tutti i parametri del chatbot secondo le tue esigenze.
- 3Caricamento documenti
Trascina e rilascia file PDF/DOCX/TXT/MD oppure inserisci l'URL di una pagina web. Puoi scegliere il tipo di documento per una strategia di suddivisione ottimale (legale, tecnico, accademico, notizie, generale).
- 4Test e incorporamento
Testa il chatbot in modalità anteprima → copia il codice di incorporamento → inseriscilo nel tuo sito web
⚡ Consigli rapidi per iniziare
📄 Preparazione dei documenti
- • Struttura: Usa intestazioni chiare, elenchi puntati e numerazioni
- • Formato: PDF con testo leggibile (non immagini scannerizzate)
- • Dimensione: La dimensione del file influisce sulla velocità di elaborazione
- • Contenuto: Rimuovi duplicati e parti irrilevanti
- • Lingua: Terminologia e stile coerenti
- • Metadati: Nomi di file chiari per una migliore organizzazione
- • Aggiornamento: Usa le versioni più recenti dei documenti
🎨 Integrazione del widget
Integrazione semplice tramite codice JavaScript:
<script src="https://chatbotty.ai/chatbot-embed.js" data-chatbot-id="xxxxxxxx"> </script>
- • Caricamento asincrono senza blocco della pagina
- • Supporto cross-domain
Gestione chatbot
➕ Creazione di chatbot
🎯 Configurazione di base
Informazioni di base:
- • Nome del chatbot: Identificazione del tuo chatbot
- • Descrizione: Breve descrizione dello scopo del chatbot
- • Stile di risposta: Formale / Amichevole / Professionale / Informale
🎨 Aspetto
Personalizzazione dell'aspetto del widget chatbot:
- • Colore tema: Selezione tra colori preimpostati
- • Messaggio di benvenuto: Testo per il primo contatto con l'utente
- • Messaggio di errore: Testo visualizzato quando il chatbot non è disponibile
- • Domini consentiti per l'incorporamento: Specifica dove può essere usato il widget
💎 Numero massimo di chatbot per piano
Free
1 chatbot
Evaluation
1 chatbot
Prova 14 giorni
Basic
1 chatbot
Elite
2 chatbot
Enterprise
3 chatbot
🗑️ Conferma eliminazione
Processo di eliminazione sicuro
Quando si elimina un chatbot, viene visualizzata una finestra di conferma per prevenire l'eliminazione accidentale. Questo assicura che non si perdano dati importanti per errore.
⚠️ Attenzione:
Tutti i dati del chatbot, i documenti e le analytics verranno rimossi definitivamente e non potranno essere recuperati.
Impostazioni avanzate chatbot
🧠 Comportamento AI e prompt
📝 Istruzioni di sistema
Definisci la personalità e il comportamento dell'assistente AI. Contiene linee guida per:
- • Stile di comunicazione e tono delle risposte
- • Comportamento generale e regole
- • Istruzioni critiche per le limitazioni
🏷️ Segnaposto disponibili
I seguenti segnaposto possono essere usati nei prompt di istruzioni e nei messaggi:
- •
{current_datetime}- Data e ora correnti - •
{chatbot_id}- Identificatore univoco del chatbot - •
{fallback_message}- Messaggio di fallback personalizzato quando non viene trovata una risposta
⚡ Qualità della ricerca e delle risposte
🔍 Parametri di ricerca
- • Soglia di similarità (0.4): Corrispondenza minima per usare il documento
- • Numero di frammenti documento nel contesto (5): Quanti frammenti di documento riceve l'AI
- • Routing intelligente del modello: Seleziona automaticamente il modello migliore in base alla complessità della query
- • Ticket di supporto automatici: Quando l'AI non riesce a rispondere, offre di creare un ticket di supporto. Richiede il consenso dell'utente e l'email.
- • Forza fallback: Se attivato, mostra sempre il messaggio di fallback per query con bassa rilevanza documentale. Se disattivato, l'AI risponde anche senza documenti rilevanti (modalità conversazionale).
⚙️ Preferenze linguistiche e parametri AI
- • Lingua di risposta del chatbot: Lingua in cui il chatbot risponderà
- • Fuso orario: Per le risposte sulla data e ora correnti
- • Creatività (temperatura): 0.0 = risposte precise, 1.0 = risposte creative
- • Lunghezza massima della risposta (token): Limite in token (≈ 375 parole per 500 token)
🛡️ Protezione anti-spam
- • Max richieste/giorno: Numero massimo di richieste da un indirizzo IP nelle 24 ore (protezione anti-bot)
- • Max richieste/sessione: Numero massimo di richieste per sessione (finestra di 2 ore per prevenzione degli abusi)
- • Limite di velocità al minuto: Protezione contro query spam
- • Cache TTL (secondi): Per quanto tempo memorizzare nella cache le risposte
🔄 Ripristina valori predefiniti
Ripristina le impostazioni predefinite
Il pulsante 'Ripristina valori predefiniti' riporta tutte le impostazioni avanzate ai valori di default. Prima del ripristino appare una finestra di conferma per evitare modifiche accidentali.
ℹ️ Nota:
Puoi sempre ripristinare le impostazioni ai valori predefiniti se vuoi ricominciare da capo o se qualcosa non funziona come previsto.
Gestione documenti
📤 Caricamento file
📋 Fonti supportate
File
PDF, DOCX, TXT, MD, HTML
Web URL
Scraping automatico
Aggiornamenti
Sostituzione automatica versioni
🎯 Preparazione ottimale dei documenti
✅ Pratiche consigliate:
- • Intestazioni e struttura chiare
- • PDF con testo leggibile (non immagini)
- • Formattazione coerente
- • Numerazione logica delle sezioni
❌ Da evitare:
- • Immagini scannerizzate senza OCR
- • Frammentazione eccessiva del testo
- • Formattazione incoerente
- • File più grandi di 10MB
💾 Limiti di archiviazione per piano
Free
10MB totali
Evaluation
20MB totali
Basic
10MB totali
Elite
20MB totali
Enterprise
50MB totali
📋 Rilevamento duplicati
Gestione intelligente dei duplicati
Quando si carica un documento con lo stesso nome di uno esistente, appare una finestra di conferma con opzioni per prevenire sovrascritture accidentali.
Opzioni disponibili:
- • Sostituisci: Sovrascrive il documento esistente con la nuova versione
- • Mantieni entrambi: Conserva entrambe le versioni (al nuovo file viene aggiunto un suffisso numerico)
📄 Processo di caricamento documenti
Seleziona chatbot
Scegli il chatbot a cui verrà assegnato il documento
Seleziona metodo di caricamento
📎 File (PDF, DOCX, TXT, MD)
Massimo 10 MB per file
🌐 Web URL
Scraping automatico della pagina web
Seleziona tipo di documento
Il sistema ottimizza automaticamente l'elaborazione per tipo:
Documento legale:
Leggi, regolamenti, contratti
Manuale tecnico:
Guide, specifiche, procedure
Notizie:
Articoli, comunicati stampa
Testo accademico:
Articoli scientifici, studi
Documento generale:
Impostazioni universali
Descrivi il documento (facoltativo)
Aggiungi una descrizione per una facile navigazione futura nell'elenco dei documenti
Suggerimento per l'aggiornamento dei file
Inserendo lo stesso nome del documento, hai la possibilità di sostituzione automatica della versione originale senza dover eliminare il documento obsoleto. I tuoi dati rimarranno sempre aggiornati.
Widget chat
🔧 Incorporamento web (visualizzazione del chatbot sul tuo sito)
📋 Come ottenere il codice di incorporamento
Puoi trovare il codice di incorporamento per ogni chatbot nel menu contestuale (tre puntini). Clicca su "Copia codice di incorporamento" e incollalo nel tuo sito web prima del tag di chiusura </body>.
<script src="https://chatbotty.ai/chatbot-embed.js" data-chatbot-id="xxxxxxxx"> </script>
💡 Suggerimento: Il widget si carica in modo asincrono e non influisce sulla velocità della tua pagina. La bolla chat appare una volta che la configurazione è stata caricata in background.
🔴 Nota: Se il chatbot è disattivato, il widget non apparirà affatto sul sito web.
⚠️ Installazione via GTM: Se incorpori il widget tramite Google Tag Manager e un visitatore rifiuta i cookie, GTM non verrà caricato e il chatbot non apparirà. Ti consigliamo di incorporare il codice direttamente in HTML, al di fuori di GTM.
⚙️ Configurazione del widget
Puoi personalizzare completamente il widget nella sezione "Aspetto" durante la modifica del chatbot. Tutte le impostazioni vengono applicate automaticamente al codice di incorporamento.
🎨 Aspetto e posizione:
- • Colore tema: 6 colori preimpostati (blu, rosso, verde, giallo, viola, arancione)
- • Posizione del widget: In basso a destra / In basso a sinistra
- • Messaggio di benvenuto: Saluto all'utente
- • Messaggio di fallback: Testo per i casi in cui il chatbot non conosce la risposta
⚙️ Comportamento del chatbot:
- • Nome del chatbot: Visualizzato nell'intestazione
- • Descrizione: Breve descrizione dello scopo del chatbot (non visualizzata sul web)
- • Stile di risposta: Professionale, amichevole, formale
- • Stato: Chatbot attivo/inattivo
🎯 Personalizzazione del widget
Opzioni di posizione:
- • In basso a destra (predefinito)
- • In basso a sinistra
Effetti bolla:
- • Effetto pulsazione - Bolla animata per attirare l'attenzione (può essere attivata/disattivata)
👁️ Anteprima del widget
Usa la finestra di anteprima del widget per testare il chatbot prima di incorporarlo:
- • Clicca il pulsante "Anteprima" nelle impostazioni del chatbot
- • Apre il widget in una finestra modale
- • Testa tutte le funzionalità e l'aspetto
- • Non richiede l'installazione del codice
🔗 Pagina pubblica del widget
Accedi al tuo widget su: /widget-embed/[widgetId]
- • Pagina autonoma per i test
- • Può essere condivisa con i membri del team
- • Non richiede l'integrazione nel sito web
💡 Suggerimento: Tutte le modifiche hanno effetto immediato su tutti i siti web con il widget incorporato. Non è necessario cambiare il codice.
⚡ Ottimizzazione delle prestazioni
🚀 Caricamento asincrono
- • Caricamento asincrono in background
- • La bolla appare una volta che la configurazione è pronta
- • Zero impatto sulla velocità della pagina principale
- • Miglioramento progressivo
💾 Cache intelligente
- • Tasso di successo cache 90%+
- • Validità configurazione di 5 minuti
- • Caricamento veloce tramite Redis
- • Funzionamento fluido anche durante un'interruzione del Redis Cache
🔒 Sicurezza e restrizioni
🌐 Restrizioni di dominio
Limita l'accesso solo ai domini consentiti:
Esempio di configurazione:
- • example.com
- • *.example.com (inclusi i sottodomini)
🛡️ Protezione anti-spam
Impostazioni del limite di richieste per la protezione contro spam e abusi
Max richieste/giorno
50
Numero massimo di richieste da un indirizzo IP nelle 24 ore (protezione anti-bot)
Max richieste/sessione
20
Numero massimo di richieste per sessione (finestra di 2 ore per prevenzione degli abusi)
Limite richieste/min
10
🛡️ Protezione contro query spam
Cache TTL (secondi)
300
⚡ Per quanto tempo memorizzare nella cache le risposte
📝 Nota:
Questi parametri sono completamente configurabili dall'utente nelle impostazioni avanzate di ogni chatbot per la massima flessibilità.
Analytics
🎯 Accesso per piano
🆓 Free
Nessun accesso
Popup di aggiornamento con istruzioni
⭐ Evaluation
Accesso completo
14 giorni di funzionalità Elite
🔵 Basic
Metriche di base
- • Conteggio messaggi
- • Query principali
- • Statistiche chatbot
👑 Elite+
Analytics dettagliata
- • Tasso di successo
- • Esportazione dati
- • Report dettagliati
- • Interfaccia interattiva
- • Analytics per ogni chatbot separatamente
🤖 Analytics dettagliata per chatbotElite+
📋 Visualizzazione per ogni chatbot
- • Panoramica individuale: Analytics separata per ogni chatbot
- • Filtraggio query: Visualizza solo le conversazioni pertinenti
- • Metriche isolate: Prestazioni dei singoli chatbot separate
- • Confronto chatbot: Possibilità di confrontare le prestazioni di diversi bot
🔍 Visualizzazione dettagliata delle query
- • Query completa: Visualizzazione dell'intera domanda dell'utente
- • Affidabilità della risposta: Valore esatto del punteggio di confidenza
- • Risposta AI: Testo completo della risposta del chatbot
- • Timestamp: Data e ora di ogni query
💡 Utilizzo pratico:Consente un'analisi precisa di come i singoli chatbot rispondono alle query degli utenti, l'identificazione delle aree problematiche e l'ottimizzazione dei documenti per ogni chatbot separatamente.
📈 Metriche disponibili
🎯 KPI principali
📊 Qualità delle risposte
⚠️ Limitazioni della cronologia dati per piano
Vengono conservati i dati corrispondenti al numero massimo di query mensili previsto dal tuo piano. I dati più vecchi vengono eliminati automaticamente per ottimizzare le prestazioni del database.
- • Free: 200 query
- • Basic: 3000 query
- • Elite: 6000 query
- • Enterprise: 10000 query
📤 Esportazione e report
📋 Disponibilità: La funzionalità di esportazione è disponibile solo per i piani Elite+ (Elite ed Enterprise).
💡 Suggerimento:Si consiglia di esportare i dati l'ultimo giorno di ogni mese per tenere traccia della cronologia completa delle query dei clienti.
💾 Formati di esportazione
- • CSV: Dati tabulari per Excel
- • JSON: Dati strutturati per API
🔍 Filtri dati
🕐 Filtri temporali:
- • Questa settimana: Ultimi 7 giorni
- • Questo mese: Mese corrente
- • Quest'anno: Anno corrente
📋 Filtri per risposta:
- • Tutte le query: Cronologia completa
- • ✓ Con risposta: Risposte riuscite
- • ⚠ Parzialmente risposto: Risposte incomplete
- • ✗ Senza risposta: Nessuna risposta
Abbonamento
🎯 Panoramica dei piani
Free
Perfect for getting started
•10MB storage
•1 chatbot
•100 requests/month
•Basic support
•✅ Conversation history
•❌ Basic analytics
•❌ Web URL scraping
•❌ Analytics export
•❌ API access
•❌ Support tickets
•❌ Webhook actions
•❌ White-label branding
•➕ Buy extra requests
Evaluation
14-day trial with Enterprise features
•10MB storage
•1 chatbot
•500 requests/month
•✅ Conversation history
•✅ Detailed analytics
•✅ Web URL scraping
•✅ Analytics export
•✅ API access
•✅ Support tickets (AI)
•✅ Webhook actions (n8n)
•❌ White-label branding
•➕ Buy extra requests
•Auto-downgrade to Free
Basic
For growing businesses
•25MB storage
•1 chatbot
•3000 requests/month (total)
•Priority support
•✅ Conversation history
•✅ Basic analytics
•❌ Web URL scraping
•❌ Analytics export
•❌ API access
•❌ Support tickets
•❌ Webhook actions
•❌ White-label branding
•➕ Buy extra requests
Elite
Most popular
•50MB storage
•2 chatbots (max)
•6000 requests/month (total)
•Priority support
•✅ Conversation history
•✅ Detailed analytics
•✅ Web URL scraping
•✅ Analytics export
•✅ API access
•❌ Support tickets
•❌ Webhook actions
•❌ White-label branding
•➕ Buy extra requests
Enterprise
Custom solutions
•100MB storage
•3 chatbots (max)
•10000 requests/month (total)
•Premium support
•✅ Conversation history
•✅ Detailed analytics
•✅ Web URL scraping
•✅ Analytics export
•✅ API access
•✅ Support tickets (AI)
•✅ Webhook actions (n8n)
•✅ White-label branding
•➕ Buy extra requests
💡 Utilizzo dei dati
10MB di dati corrispondono a circa 1000 pagine di documento PDF. Nei formati puramente testuali, anche molto di più.
Attenzione: La dimensione originale del file caricato conta verso i limiti dei dati. Le immagini incorporate nei documenti possono aumentare significativamente la dimensione del file caricato.
💰 Abbonamento annuale
Risparmia 2 mesi con la fatturazione annuale – paga solo 10 mesi!
La fatturazione annuale offre un risparmio significativo rispetto ai pagamenti mensili. Puoi cambiare il periodo di fatturazione o l'abbonamento in qualsiasi momento.
⏰ Scadenza del periodo di prova
- • Downgrade automatico al piano Free dopo 14 giorni
- • Transizione senza problemi senza perdita di dati
📊 Monitoraggio dell'utilizzo
📊 Monitoraggio dashboard
Monitora l'utilizzo del tuo piano direttamente in tempo reale:
📈 Limiti mensili
- • Numero di messaggi al mese
- • Previsione fino a fine mese
- • Ripristino automatico ogni mese
📋 Limiti permanenti
- • Capacità di archiviazione (MB/MB)
- • Numero di chatbot (conteggio/limite)
📊 Statistiche
- • Totale chatbot creati
- • Chatbot attivi e funzionanti
- • Totale query degli utenti
- • Documenti caricati
📈 Visualizzazione
- • Barre di avanzamento colorate
- • Monitoraggio in tempo reale
⚠️ Applicazione dei limiti
- • Archiviazione superata: Caricamento bloccato con prompt di aggiornamento
- • Limite chatbot: Creazione bloccata, viene mostrata la finestra di aggiornamento
- • Messaggi mensili: Il widget non si carica (errore silenzioso)
- • Accesso analytics: Restrizioni delle funzionalità per piano
💰 Extra Messages Add-ons
Extra messages are additional message packages you can purchase to extend your monthly quota. Unlike monthly subscriptions, extra messages never expire and persist across billing cycles.
🔄 How it works:
- Your monthly quota is consumed first
- When monthly quota is exhausted, extra messages are automatically used
- Extra messages persist until fully consumed (no expiration)
- Visible on dashboard with real-time tracking
📦 Available Packages:
💡 When to buy:
- • Seasonal traffic spikes
- • Special campaigns
- • Testing before upgrade
- • One-time high usage
💳 Purchase:Click "Buy Extra Messages" on dashboard or in usage tracking card when approaching limit.
Fatture
📋 Panoramica
Tutte le tue fatture e la cronologia dei pagamenti sono disponibili direttamente nel portale clienti. Puoi trovarvi abbonamenti, acquisti di componenti aggiuntivi e tutti i pagamenti precedenti.
🔗 Come accedere
- Vai su Abbonamento nella barra laterale del dashboard
- Clicca il pulsante Gestisci abbonamento
- Verrai reindirizzato al portale clienti dove puoi visualizzare tutte le fatture e la cronologia dei pagamenti
Impostazioni
👤 Gestione account utente
📝 Cambia nome
Informazioni personali
- • Nome: Nome utente visualizzato
- • Può essere modificato in qualsiasi momento
- • Appare nel profilo e nelle comunicazioni
📧 Cambia email
Dopo aver inviato il nuovo indirizzo, vengono inviati link di conferma sia alla tua email attuale che a quella nuova. La modifica ha effetto solo dopo aver cliccato entrambi i link.
- • Controlla la tua casella di posta attuale e conferma da lì
- • Controlla la tua nuova casella di posta e conferma da lì
- • Solo dopo entrambe le conferme la nuova email diventerà attiva
🔒 Cambia password
La password deve contenere almeno 6 caratteri
Requisiti della password:
- • Minimo 6 caratteri
- • Combinazione di lettere e numeri
- • Password attuale richiesta
Password dimenticata:
- • Ripristino via email
- • Link di ripristino sicuro
- • Consegna immediata
🌐 Impostazioni lingua
Passa dall'interfaccia inglese a quella ceca
- • Clicca il selettore della lingua nella navigazione superiore
- • Lingue disponibili: Inglese (EN) / Ceco (CS)
- • Ricaricamento automatico della pagina - La pagina si ricarica automaticamente dopo il cambio di lingua per applicare tutte le traduzioni
- • La preferenza della lingua viene salvata nel tuo account
⚠️ Zona pericolosa
Le azioni in questa sezione sono irreversibili. Procedere con cautela.
⚠️ L'eliminazione del tuo account rimuoverà definitivamente tutti i tuoi dati, chatbot, documenti e conversazioni. Questa operazione è irreversibile.
Il pulsante "Elimina account" attiverà la rimozione completa di tutti i dati dal database.
API
🚀 Accesso programmatico ai chatbot
💎 Disponibile per i piani superiori
L'accesso API è disponibile per gli utenti con piani di abbonamento Evaluation, Elite ed Enterprise. Ti permette di integrare i tuoi chatbot in applicazioni personalizzate, siti web o sistemi.
📋 Cosa ottieni
- • REST API: Richieste HTTP standard
- • Esempi di codice: JavaScript, Python, PHP, Node.js
- • Chatbot ID: Identificatore univoco per ogni chatbot
- • Documentazione completa: Disponibile direttamente nell'app
💡 Come iniziare:Dopo aver effettuato l'accesso all'applicazione, troverai la sezione "Integrazione API" nel menu, dove puoi accedere a istruzioni dettagliate inclusi esempi di connessione per vari linguaggi di programmazione e campioni di test.
🔐 Autenticazione API
Come funziona
L'accesso API utilizza l'autenticazione con token Bearer. Ogni chiave API è collegata a uno specifico chatbot.
- Crea la chiave API nel dashboard → Integrazione API per il tuo chatbot
- Includi la chiave API nell'intestazione Authorization come token Bearer
- Invia una richiesta POST all'endpoint
/api/chat - Il chatbot viene identificato automaticamente dalla chiave API
Importante: NON è necessario inviare chatbot_id nel corpo della richiesta. Il chatbot viene determinato dalla tua chiave API.
🔑 Gestione chiavi API
Crea chiavi API
Genera chiavi API sicure per l'accesso programmatico ai tuoi chatbot.
Funzionalità:
- • Nomi personalizzati - Etichetta le chiavi per una facile identificazione
- • Massimo 50 chiavi - Limite per chatbot
- • Token sicuri - Il token completo viene mostrato solo una volta alla creazione
- • Monitoraggio attività - Timestamp dell'ultimo utilizzo
- • Attiva/disattiva - Disattivazione temporanea senza eliminazione
Sicurezza:
- • I token sono mascherati nell'interfaccia (mostra solo i primi/ultimi caratteri)
- • Copia negli appunti per un uso facile
- • Elimina immediatamente le chiavi compromesse
⚡ Quota mensile:L'utilizzo API conta verso il limite mensile di messaggi. I messaggi extra possono essere acquistati quando la quota viene superata.
💻 Esempi di codice
JavaScript (Browser)
// 1. first request – no conversation_id needed
const response = await fetch('https://chatbotty.ai/api/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: 'What is your return policy?'
// conversation_id not required – created automatically
})
})
const result = await response.json()
const conversationId = result.data.conversation_id // save for follow-up requests
// 2. follow-up request – previous messages loaded as context
const response2 = await fetch('https://chatbotty.ai/api/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: 'What about exchanges?',
conversation_id: conversationId
})
})Node.js
const response = await fetch('https://chatbotty.ai/api/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: 'What is your return policy?',
conversation_id: conversationId // optional: to continue a conversation
})
})
const result = await response.json()
console.log(result.data.message)
// result.data.conversation_id – save for follow-up requestsPython
import requests
response = requests.post(
'https://chatbotty.ai/api/chat',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'message': 'What is your return policy?',
'conversation_id': conversation_id # optional: to continue a conversation
}
)
result = response.json()
print(result['data']['message'])PHP
<?php
$ch = curl_init('https://chatbotty.ai/api/chat');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer YOUR_API_KEY',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'message' => 'What is your return policy?',
'conversation_id' => $conversationId // optional: to continue a conversation
]));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
echo $result['data']['message'];
?>cURL
curl -X POST https://chatbotty.ai/api/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What is your return policy?"}'📋 Formato della risposta
Risposta riuscita
{
"success": true,
"data": {
"message": "AI response text...",
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"sources": [
{
"content": "Relevant document excerpt...",
"similarity": 0.95,
"page": 1
}
],
"metadata": {
"tokensUsed": 150,
"cached": false,
"responseTime": 1234,
"searchResults": 3
}
},
"timestamp": "2025-01-28T10:00:00.000Z"
}Risposta di errore
{
"success": false,
"error": "Internal server error",
"timestamp": "2025-01-28T10:00:00.000Z"
}⚠️ Note importanti
- • Le chiavi API sono specifiche per chatbot - Ogni chiave funziona con un solo chatbot
- • Fino a 50 chiavi per chatbot - Crea più chiavi per diverse applicazioni
- • Le chiavi possono essere disabilitate - Disattiva temporaneamente senza eliminare
- • Si applica la quota mensile - Limitata dai messaggi/mese del tuo piano + messaggi extra acquistati
- • Nessun limite di velocità al minuto - L'API è progettata per l'accesso programmatico senza limiti di velocità
- • Nessuna validazione di dominio - L'API funziona da qualsiasi origine (usare con cautela)
- • Contesto della conversazione - Ogni risposta restituisce un
conversation_id. Passalo nelle richieste successive per mantenere il contesto — il sistema carica automaticamente gli ultimi 20 messaggi. Senzaconversation_id, ogni richiesta inizia una nuova conversazione indipendente senza contesto — va benissimo se non hai bisogno di memoria conversazionale (ad es. ricerche dati una tantum). - • Proteggi le tue chiavi - Non esporre mai le chiavi API nel codice lato client
Conversazioni
📝 Come funziona
La funzione Cronologia conversazioni registra automaticamente tutte le sessioni chatbot con metadati completi per analytics, conformità e scopi di garanzia della qualità.
- • Registrazione sessione: Ogni conversazione viene registrata con un ID di sessione univoco
- • Monitoraggio metadati: Indirizzo IP, URL della pagina, referrer, user agent
- • Timestamp: Tempi precisi per ogni scambio di messaggi
- • Informazioni di contatto: Email e nome forniti dall'utente quando disponibili
🔍 Visualizzazione delle conversazioni
Accedi alla cronologia delle conversazioni dal dashboard → Conversazioni nel menu principale.
Filtri disponibili:
- • Periodo: Filtra per periodo di tempo (questo mese, ultimi 7 giorni, ecc.)
- • Filtro (Chatbot): Mostra le conversazioni per un chatbot specifico o tutti
- • Fonte: Filtra per fonte (widget, API, ecc.)
Colonne visualizzate:
- • ID sessione, Data/Ora, Nome chatbot
- • Conteggio messaggi, Fonte, Email di contatto
- • Indirizzo IP (anonimizzato), URL della pagina
📋 Dettagli della conversazione
Clicca su qualsiasi conversazione per visualizzare la cronologia completa dei messaggi con informazioni dettagliate.
- • Timeline messaggi: Tutte le domande degli utenti e le risposte AI
- • Dati temporali: Timestamp esatti per ogni messaggio
- • Metadati fonte: URL della pagina, referrer, user agent
- • Informazioni di contatto: Email e nome se forniti dall'utente
💡 Suggerimento: Usa la cronologia delle conversazioni per identificare le domande frequenti e migliorare la knowledge base del tuo chatbot. I modelli nelle query degli utenti possono aiutarti ad aggiungere la documentazione mancante.
Ticket di supporto
Funzionalità Enterprise
I ticket di supporto basati sull'AI sono disponibili solo per gli utenti del piano Enterprise.
🤖 Come funziona
Il sistema di ticket di supporto AI rileva automaticamente quando il chatbot non riesce a rispondere alla domanda di un utente e offre di creare un ticket di supporto per il follow-up umano.
- • Rilevamento intelligente: L'AI riconosce quando non riesce a fornire una risposta soddisfacente
- • Consenso dell'utente: Il sistema chiede all'utente se vuole creare un ticket
- • Raccolta email: Raccoglie l'email dell'utente per il follow-up
- • Riepilogo AI: Genera un riepilogo della conversazione per il team di supporto
📝 Flusso di creazione ticket
Il flusso di conversazione multi-turno per la creazione dei ticket:
- Attivazione: L'AI rileva una domanda senza risposta o l'utente esprime frustrazione
- Offerta: "Vuoi che crei un ticket di supporto per te?"
- Consenso: L'utente conferma di voler procedere
- Email: "Fornisci il tuo indirizzo email per il follow-up"
- Riepilogo: L'AI genera automaticamente un riepilogo della conversazione
- Conferma: Ticket creato con numero di riferimento
📋 Gestione dei ticket
Accedi e gestisci i ticket di supporto dal dashboard → Ticket di supporto.
Flusso di stato:
- • Aperto: Nuovo ticket in attesa di revisione
- • In corso: Il team di supporto sta lavorando sul problema
- • Risolto: Problema affrontato, in attesa di conferma
- • Chiuso: Ticket completato e archiviato
Azioni disponibili:
- • Visualizza il contesto completo della conversazione
- • Aggiorna lo stato del ticket
- • Aggiungi note interne
- • Invia risposta email all'utente
⚙️ Configurazione
Abilita e configura i ticket di supporto in Impostazioni chatbot → Scheda Ticket di supporto.
- • Abilita/Disabilita: Attiva/disattiva la creazione di ticket per questo chatbot
- • Notifiche email: Ricevi avvisi per nuovi ticket
- • Risposta automatica: Messaggio personalizzato inviato all'utente dopo la creazione del ticket
- • Trigger: Configura quando vengono fatte le offerte di ticket
💡 Suggerimento: Rivedi i ticket regolarmente per identificare le lacune nella tua knowledge base. I temi comuni dei ticket indicano aree in cui dovresti aggiungere ulteriore documentazione.
Azioni webhook
Funzionalità Enterprise e Evaluation
Le azioni webhook sono disponibili per gli utenti del piano Enterprise (fino a 10 webhook, fino a 10 strumenti totali su tutti i webhook) e Evaluation (fino a 5 webhook, fino a 5 strumenti totali su tutti i webhook).
🔗 Panoramica
Le azioni webhook consentono al tuo chatbot di interagire con sistemi esterni tramite chiamate a strumenti attivate dall'AI. Definisci webhook personalizzati con strumenti specifici che l'AI può invocare durante le conversazioni.
- • Webhook personalizzati: Definisci endpoint con autenticazione
- • Strumenti AI: Specifica gli strumenti che l'AI può chiamare (es. get_order_status)
- • Parametri: Definisci i parametri obbligatori e facoltativi per ogni strumento
- • Gestione delle risposte: L'AI elabora naturalmente le risposte webhook
⚙️ Configurazione dei webhook
Configura i webhook nel dashboard → Webhook per ogni chatbot.
- Crea webhook: Inserisci nome, URL e intestazioni di autenticazione opzionali
- Definisci strumenti: Aggiungi strumenti che l'AI può chiamare (es. get_order_status, check_inventory)
- Imposta parametri: Definisci i parametri obbligatori (es. order_id, product_sku)
- Test: Usa la funzione di test per verificare che il tuo webhook funzioni correttamente
- Attiva: Abilita il webhook per l'uso in produzione
🔄 Integrazione n8n
n8n è un potente strumento di automazione dei flussi di lavoro che si integra perfettamente con il nostro sistema webhook.
Configurazione rapida:
- Crea un nuovo flusso di lavoro in n8n
- Aggiungi un nodo trigger Webhook (metodo POST)
- Copia l'URL del webhook nella configurazione webhook del tuo chatbot
- Costruisci la logica del tuo flusso di lavoro (chiamate API, query database, ecc.)
- Restituisci una risposta JSON che l'AI elaborerà
Formato di risposta di esempio:{"status": "shipped", "tracking": "1Z999AA1", "eta": "2024-01-15"}
💡 Esempi di casi d'uso
📦 Ricerca stato ordine
Il cliente chiede "Dov'è il mio ordine?" → L'AI chiama get_order_status con il numero d'ordine → Restituisce le informazioni di tracking
👤 Integrazione CRM
L'utente fornisce l'email → L'AI chiama lookup_customer → Restituisce i dettagli dell'account e l'attività recente
📅 Prenotazione appuntamento
L'utente richiede un appuntamento → L'AI chiama check_availability poi book_appointment → Conferma la prenotazione
🔍 Verifica inventario
Il cliente chiede della disponibilità del prodotto → L'AI chiama check_stock → Restituisce l'inventario corrente
🔒 Sicurezza
- • HTTPS obbligatorio: Tutti gli endpoint webhook devono utilizzare HTTPS
- • Intestazioni personalizzate: Aggiungi token di autenticazione nelle intestazioni
- • Gestione timeout: Timeout di 30 secondi per prevenire richieste bloccate
- • Protezione SSRF: Gli indirizzi IP privati sono bloccati per sicurezza
- • Limitazione della velocità: Protezione integrata contro chiamate eccessive
⚠️ Importante: Non esporre mai le chiavi API sensibili negli URL webhook. Usa invece le intestazioni di autenticazione.
💡 Suggerimento: Inizia con operazioni semplici di sola lettura (come la ricerca degli ordini) prima di implementare operazioni di scrittura. Testa accuratamente usando il tester webhook integrato prima di attivare in produzione.
Consigli & Trucchi per la preparazione dei documenti e l'implementazione efficace del chatbot
📄 Preparazione dei documenti
📋 Strutturazione dei contenuti
- • Divisione tematica: Un file = un argomento
- • Struttura logica: Sezioni e intestazioni chiare
- • Aggiornamenti facili: Modifica solo le parti pertinenti
- • Chiarezza: Orientamento rapido nei contenuti
📝 Formato e denominazione
- • Formati di testo: TXT, DOC, DOCX (senza immagini)
- • Nomi chiari: Nomi di file descrittivi
- • Aggiornamento automatico: Stesso nome = sostituzione
- • Senza preoccupazioni: La versione precedente viene eliminata automaticamente
💡 Suggerimento: Prepara i documenti in anticipo in formato testo normale. Le immagini e la formattazione complessa possono peggiorare la qualità delle risposte del chatbot.
🎯 Ricerca semantica
🔍 Come il chatbot trova le risposte
- • Corrispondenza semantica: Cerca un significato simile, non il testo esatto
- • Parole chiave: Identifica i termini importanti nella query
- • Contesto: Considera il significato dell'intera frase
- • Similarità: Confronta con le informazioni esistenti
✍️ Formulazione ottimale
- • Risposte dirette: "X ha Y anni" invece di "X ha celebrato Y anni"
- • Varie formulazioni: Usa diversi modi di espressione
- • Domande previste: Pensa alle possibili query degli utenti
- • Parole chiave: Includi sinonimi e varianti
❌ Meno adatto:
"Il Big Ben ha celebrato il suo 165° anniversario"
✅ Meglio:
"Il Big Ben ha 165 anni"
Perché:La seconda versione risponde meglio a domande come "Quanti anni ha il Big Ben?" o "Qual è l'età del Big Ben?"
📊 Ottimizzazione basata sull'analytics
🔍 Analisi dei gap
- • Query senza risposta: Traccia le domande frequenti senza risposta
- • Bassa affidabilità: Identifica le query con bassa confidenza
- • Problemi ricorrenti: Trova i modelli nelle query senza successo
- • Frustrazioni degli utenti: Osserva i punti in cui gli utenti si "bloccano"
🎯 Miglioramenti mirati
- • Espansione dei documenti: Aggiungi le informazioni mancanti
- • Riformulazione: Chiarisci i passaggi poco chiari
- • Nuove formulazioni: Aggiungi diversi modi di espressione
- • Test e iterazione: Testa le modifiche e misura i miglioramenti
💯 Interpretazione dell'affidabilità
< 30%
Risposta fallita
30-40%
Parzialmente risposto
> 40%
Risposta riuscita
💡 Suggerimento:Testa le tue modifiche direttamente nel chatbot. Fai le stesse domande di nuovo e monitora i cambiamenti nell'affidabilità. L'obiettivo è raggiungere costantemente oltre il 40% di affidabilità.
Perché valori così bassi?Per un'affidabilità del 100%, la query dovrebbe essere identificata esattamente con le stesse parole nel documento, il che accade molto raramente. Pertanto, i valori realistici per l'ambiente italiano sono più bassi.
❓ Ottimizzazione FAQ
📈 Analisi delle query più frequenti
- • Traccia le tendenze: Identifica le domande ricorrenti
- • Prioritizzazione: Concentrati sulle query più frequenti
- • Modelli: Cerca formulazioni simili della stessa domanda
- • Problemi: Trova le query con bassa affidabilità
📝 Creazione di documenti FAQ
- • Un paragrafo = Q&A: Domanda e risposta insieme
- • Linguaggio naturale: Usa formulazioni comuni
- • Risposte complete: Tutte le informazioni necessarie in una volta
- • Varie varianti: Includi sinonimi e alternative
✨ Esempio di FAQ ottimizzata
Quanto tempo richiede l'elaborazione della richiesta di passaporto?L'elaborazione della richiesta di passaporto richiede normalmente 6-8 settimane dalla presentazione di una domanda completa. Per esigenze di viaggio urgenti, è disponibile l'elaborazione accelerata entro 2-3 settimane con un supplemento di €60. Puoi ritirare il passaporto di persona al centro di raccolta domande o fartelo spedire al tuo indirizzo.
🚀 Risultato:Il documento FAQ aumenta drasticamente l'affidabilità delle risposte alle query più frequenti. Soddisferai l'80-90% delle domande degli utenti con alta precisione.
📊 Analisi a lungo termine
🔍 Monitoraggio regolare
- • Controllo settimanale: Traccia le risposte senza successo
- • Panoramica mensile: Analizza tendenze e cambiamenti
- • Risposte parziali: Identifica le aree di miglioramento
- • Modelli di problemi: Trova le carenze ricorrenti
📤 Esportazione analyticsElite+
- • Formato CSV: Per MS Excel e Numbers
- • Dati dettagliati: Tutte le query e le risposte
- • Affidabilità: Livello di confidenza per ogni query
- • Timestamp: Monitoraggio delle tendenze nel tempo
📈 Flusso di lavoro consigliato
1. Esportazione settimanale
Scarica i dati della settimana scorsa
2. Analisi Excel
Filtra per affidabilità < 40%
3. Aggiornamenti
Modifica i documenti in base alle intuizioni
💡 Per utenti avanzati: Usa le tabelle pivot di Excel per raggruppare query simili e identificare le aree problematiche più comuni.
🌐 Utilizzo di fonti web
🔗 Scraping Web URLElite+
- • Importazione diretta: Carica contenuti dai siti web
- • Sezioni FAQ: Ideale per le Domande Frequenti esistenti
- • Documentazione: Usa la documentazione già pronta esistente
- • Contenuto aggiornato: Sempre l'ultima versione delle informazioni
✅ Vantaggi del web scraping
- • Risparmio di tempo: Nessuna riscrittura manuale
- • Coerenza dei dati: Nessuna differenza tra siti web e chatbot
- • Aggiornamenti automatici: Basta ricaricare l'URL
- • Contenuto strutturato: La formattazione viene preservata
📋 Fonti ideali per lo scraping
✅ Pagine adatte:
- • Sezioni FAQ
- • Documentazione prodotto
- • Guide e procedure
- • Informazioni di contatto
❌ Meno adatte:
- • Pagine con molte immagini
- • Menu di navigazione
- • Contenuto pubblicitario
- • Contenuto generato da JavaScript
💡 Suggerimento: Se hai FAQ o documentazione di qualità sul tuo sito web, usa lo scraping URL invece della riscrittura manuale. Questo previene le incoerenze e risparmia tempo durante gli aggiornamenti.
💡 Consigli per ottenere il massimo valore
Ottieni risposte migliori dal tuo chatbot e sfrutta al massimo la quota mensile di messaggi con questi consigli:
📄 Qualità dei documenti:
- • Rimuovi i contenuti non necessari prima del caricamento — documenti più puliti = risposte più accurate
- • Usa documenti ben strutturati con intestazioni e sezioni chiare
- • Evita informazioni duplicate tra i documenti
❓ Incoraggia domande pertinenti:
- • Le domande specifiche e mirate ottengono risposte migliori rispetto a quelle vaghe
- • I documenti ben preparati portano a risposte più rapide e precise
📊 Monitora il tuo utilizzo:
- • Tieni traccia della tua quota messaggi nell'analytics del dashboard
- • Per i picchi di traffico stagionali, usa i componenti aggiuntivi di messaggi extra invece di aggiornare il piano
- • Rivedi le tendenze mensili per decidere se il tuo piano attuale soddisfa le tue esigenze
Risoluzione problemi
⚠️ Problemi comuni
🤖 Chatbot non risponde
Possibili cause:
- • Limite mensile di messaggi superato
- • Il dominio è bloccato dalle restrizioni
- • Limitazione della velocità attivata
- • Errore di caricamento del widget
Soluzione:
- • Controlla l'utilizzo nel dashboard
- • Verifica i domini consentiti
- • Strumenti per sviluppatori del browser → Scheda Rete
- • Contatta il supporto con i dettagli dell'errore
📄 Il documento non viene elaborato
Problemi comuni:
- • File più grande del limite del piano
- • Formato non supportato
- • PDF danneggiato o protetto da password
- • Sovraccarico della coda di elaborazione
Diagnostica:
- • Controlla la dimensione del file rispetto al limite del piano
- • Prova a selezionare il testo nel PDF
- • Stato di elaborazione nei documenti
- • Riprova il caricamento se bloccato
🌐 Il widget non si carica
Problemi di caricamento:
- • Blocco della policy CORS
- • Timeout di caricamento dello script
- • CSP (Content Security Policy)
- • Interferenza del blocco annunci
Passaggi soluzione:
- • Messaggi di errore nella console del browser
- • Prova un browser diverso/modalità in incognito
- • Disabilita temporaneamente i blocchi annunci
- • Controlla le impostazioni dei domini consentiti
🆘 Contattare il supporto
📧 Supporto via email
support@chatbotty.ai
- • Piani prioritari: entro 24h (eccezionalmente fino a 48h)
- • Piani gratuiti: solitamente entro 72h
- • Allegati: screenshot, log sono benvenuti
🔍 Informazioni da includere
- • Tipo e versione del browser
- • Messaggio di errore o screenshot
- • ID del chatbot e URL del widget
- • Passaggi per riprodurre il problema
- • Errori della console (F12)