Manuale utente

Impostazioni

Ogni bot può essere personalizzato in modo approfondito: modello di intelligenza artificiale, personalità e tono delle risposte, lingua dell'interfaccia, aspetto grafico del widget, messaggi di benvenuto, raccolta dati pre-chat, handoff verso operatori umani, scansione automatica del sito, notifiche e molto altro.

Dashboard Bot

La dashboard del bot è la pagina principale che si apre quando selezioni un bot. Offre una panoramica completa dello stato e dell'attività del bot.

Configurazione attiva

In alto trovi un riepilogo della configurazione corrente del bot: modello di ragionamento, personalità, tono, lingua e funzionalità attive.

Statistiche Knowledge Base

Il pannello delle statistiche mostra quante sorgenti (file, pagine web, snippet) e quanti chunks (blocchi di testo indicizzati) compongono la Knowledge Base. Più chunks ha il bot, più ampio è il suo bagaglio di conoscenze.

Consumi

La sezione consumi mostra l'utilizzo del bot nel mese corrente: numero di messaggi scambiati, sorgenti utilizzate e spazio di archiviazione occupato. Se il bot ha dei limiti configurati (quota), vedrai anche le barre di avanzamento.

Monitoraggio errori

Se il bot riscontra errori nelle chiamate ai sistemi di intelligenza artificiale a cui esso è collegato (ad esempio per sovraccarico temporaneo del servizio), vengono mostrati qui con il conteggio per tipologia. Il bot ha un sistema di retry automatico: riprova la richiesta fino a 2 volte prima di restituire un messaggio di errore all'utente.

Configurazione Widget

Per i bot pubblici, questa sezione mostra il codice di embed per integrare il chatbot nel tuo sito web, il QR code per accesso diretto e le opzioni di condivisione.

Chat standalone

Ogni bot dispone di un link diretto che apre il chatbot in una pagina dedicata a schermo intero, senza bisogno di integrarlo in un sito web. L'URL è basato sul nome interno del bot (es. /chat/nome-bot) ed è sempre attivo. Dalla dashboard puoi anche generare un QR code da scaricare e stampare.

Knowledge Base — Pagine Web

Importa le pagine del tuo sito web per permettere al bot di rispondere con informazioni sempre aggiornate. Il sistema scarica il contenuto delle pagine, lo pulisce da elementi di navigazione e lo indicizza.

Modalità di importazione

• URL singolo — importa una singola pagina. Ideale per pagine specifiche come FAQ, Chi siamo, Contatti. Puoi aggiungere una nota descrittiva per contestualizzare il contenuto
• Scansiona Sito — trova e importa più pagine automaticamente:
  • Inserisci il dominio (es. https://esempio.com) per scansionare tutto il sito
  • Inserisci una cartella (es. https://esempio.com/prodotti/) per scansionare solo quella sezione
  • Per siti multilingua, usa il prefisso lingua (es. https://esempio.com/it) per importare solo una versione linguistica

Gestione delle pagine

• Modifica (icona matita) — apre una finestra con tre campi:
  • Titolo — usato dal bot come ancora tematica del contenuto
  • Note — contesto aggiuntivo per il bot, iniettato nei chunks per migliorare la pertinenza
  • Priorità — autorevolezza relativa della pagina rispetto alle altre sorgenti della Knowledge Base
• Anteprima estrazione — mostra esattamente il testo che il bot vede dopo la pulizia dell'HTML. Da questa finestra puoi anche attivare l'AI Rewriter per migliorare la struttura del contenuto (vedi sotto)
• Refresh singola pagina — riscansiona una pagina già importata per aggiornarne il contenuto. Il sistema rileva automaticamente se la pagina è effettivamente cambiata, evitando una re-indicizzazione inutile
• Svuota tutte le pagine — rimuove tutte le pagine web e i relativi chunks dal bot in una volta (operazione irreversibile, richiede conferma)

AI Rewriter

Alcune pagine web hanno una struttura HTML che, dopo la pulizia, produce un testo difficile da usare per il bot — tabelle di confronto, layout a colonne, prezzi senza contesto. L'AI Rewriter rielabora il testo estratto per recuperare la struttura semantica persa.

Per attivarlo: apri l'anteprima estrazione della pagina, verifica il testo estratto, attiva il toggle AI e clicca Salva. Il risultato rielaborato viene salvato e usato direttamente, senza alcuna chiamata AI aggiuntiva al momento dell'indicizzazione.

Le pagine con AI Rewriter attivo mostrano un badge AI. Le scansioni automatiche future rigenereranno il testo con l'AI a ogni aggiornamento del contenuto.

Scansione automatica

Qualita del contenuto

Le pagine web contengono spesso elementi di navigazione, footer e sidebar che possono introdurre "rumore". Il sistema effettua una pulizia automatica, ma il risultato non è sempre perfetto. Eventuali annunci pubblicitari o contenuti fuori contesto presenti nelle pagine potrebbero confondere il bot nelle risposte. Per risultati migliori preferisci pagine con contenuto ricco e ben strutturato (articoli, pagine prodotto, FAQ) rispetto a pagine con poco testo, elenchi di link o pagine prevalentemente grafiche.

Best practice

• Per siti multilingua, importa una sola versione linguistica usando il prefisso lingua nell'URL — il bot è in grado di rispondere in qualsiasi lingua indipendentemente dalla lingua dei dati
• Se il contenuto di una pagina cambia, usa il pulsante refresh per aggiornarla, oppure chiedi all'amministratore di attivare la scansione automatica
• Evita di importare pagine con contenuto duplicato o molto simile, in quanto creerebbe solo confusione nei meccanismi di ragionamento del bot
• Controlla il risultato dell'importazione: se una pagina mostra poco testo potrebbe essere basata su JavaScript e non importabile correttamente
• Aggiungi titolo e note descrittivi alle pagine importate (icona matita) per migliorare la pertinenza delle risposte
• Usa l'anteprima estrazione per verificare la qualità del testo importato prima di attivare l'AI Rewriter

Knowledge Base — Prodotti

Cos'è questa sezione

Qui trovi il catalogo prodotti importato dal tuo negozio. Ogni prodotto viene indicizzato nella Knowledge Base così il bot può rispondere su nome, prezzo, disponibilità e dettagli. I prodotti sono in sola lettura: si gestiscono nel tuo negozio, qui vengono solo sincronizzati.

Sincronizzazione

• Premi Sincronizza ora per importare o aggiornare il catalogo dal negozio
• La sincronizzazione gira in background: lo stato e l'orario dell'ultimo sync si aggiornano automaticamente
• Se hai attivato la sincronizzazione real-time (webhook in entrata), le modifiche nel negozio arrivano da sole, senza premere il pulsante

Stati di sincronizzazione

• Aggiornato — catalogo importato correttamente
• In corso — sincronizzazione in esecuzione
• Parziale — alcuni prodotti non sono stati importati (es. limite del piano raggiunto)
• Errore — la sincronizzazione è fallita: controlla le credenziali nella pagina Negozio

Prodotti indicizzati e limite

Il contatore mostra quanti prodotti sono indicizzati rispetto al limite del piano. Se raggiungi il limite, la sincronizzazione si ferma e lo stato diventa Parziale: i prodotti eccedenti non vengono importati. Per aumentare il limite, contatta l'amministratore.

Disponibilità

Ogni prodotto mostra un'etichetta di disponibilità:

• Disponibile — prodotto a magazzino
• Esaurito — non disponibile
• Su ordine — ordinabile con tempi di attesa

Knowledge Base — Files

In questa sezione puoi caricare documenti che il bot utilizzerà come fonte di conoscenza. I file vengono automaticamente suddivisi in blocchi di testo (chunks) e indicizzati per la ricerca semantica.

Formati supportati

• PDF — manuali, cataloghi, brochure. Deve contenere testo selezionabile; i PDF con sole immagini vengono elaborati tramite OCR, ma con risultati potenzialmente imperfetti
• TXT / MD — testi semplici e documentazione
• DOCX — documenti Microsoft Word
• PPTX — presentazioni PowerPoint
• CSV — tabelle e dati strutturati

Titolo, note e priorità

Ogni file caricato dovrebbe avere un titolo descrittivo e delle note che aiutino il bot a capire il contesto del documento. Le note vengono iniettate nei chunks per migliorare la pertinenza delle risposte. Clicca l'icona matita nella riga del file per aprire la finestra di modifica.

Esempio: un file chiamato "doc_2024.pdf" non dice nulla al bot sul suo contenuto. Rinominandolo con il titolo "Catalogo Prodotti Primavera 2024" e aggiungendo le note "Prezzi, taglie e specifiche tecniche della collezione abbigliamento primavera/estate", il bot saprà contestualizzare molto meglio le informazioni contenute nel documento.

La priorità indica al bot quanto questa sorgente sia autorevole: "Alta" la favorisce in caso di pareggio con altri documenti, "Bassa" la deprioritizza. L'effetto è leggero e non sostituisce la pertinenza semantica — usala solo quando sai che una sorgente è più o meno affidabile delle altre.

Come funziona l'indicizzazione

Quando carichi un file, il sistema lo elabora automaticamente:

1. Estrae il testo dal documento
2. Lo suddivide in chunks (blocchi di testo) di dimensione ottimale
3. Genera gli embeddings (rappresentazioni matematiche) per ciascun chunk
4. Indicizza i chunks per la ricerca semantica

Documenti ben strutturati, con titoli e paragrafi chiari, producono chunks di qualità superiore e risposte più precise.

L'aggiunta di titoli e note dettagliate e pertinenti aiuta il bot a fornire risposte migliori alle richieste degli utenti.

Best practice

• Preferisci documenti piccoli e mirati rispetto a PDF monolitici di centinaia di pagine
• I PDF con scansioni di immagini vengono elaborati tramite OCR, ma il risultato potrebbe non essere perfetto: se possibile, preferisci PDF con testo selezionabile
• Rimuovi pagine irrilevanti (copertine, indici, pagine bianche) prima del caricamento
• Se aggiorni un documento, elimina la vecchia versione e ricarica quella nuova
• Usa il pulsante "Svuota tutti i file" per rimuovere tutti i file e i relativi chunks in una volta (operazione irreversibile, richiede conferma)

Knowledge Base — Snippet

Gli snippet sono blocchi di testo libero che puoi scrivere direttamente nel pannello. Sono ideali per informazioni che non esistono in nessun documento o pagina web: orari di apertura, contatti specifici, politiche aziendali, istruzioni operative, ecc.

Quando usare gli snippet

Usa gli snippet per tutte quelle informazioni "volatili" o specifiche che non si trovano altrove:

• Orari di apertura e chiusure straordinarie
• Contatti di emergenza o specifici per reparto
• Politiche e condizioni particolari
• Informazioni temporanee (promozioni, eventi)

Come strutturare il contenuto

• Usa un titolo chiaro e descrittivo per ogni snippet
• Organizza le informazioni in paragrafi brevi, un concetto per paragrafo
• Usa elenchi puntati per liste (orari, servizi, prezzi)
• Raggruppa le informazioni correlate nello stesso snippet

Best practice

• Scrivi in modo semplice e diretto
• Aggiorna gli snippet quando le informazioni cambiano
• Meglio tanti snippet brevi e specifici che un unico snippet lunghissimo con informazioni eterogenee
• Il pulsante "Svuota tutti gli snippet" rimuove tutti gli snippet in una volta (operazione irreversibile)

Knowledge Base — Q&A

Le Q&A (domanda-risposta) sono diverse da tutte le altre fonti: quando il bot trova una corrispondenza con una domanda, restituisce la risposta esatta che hai scritto, senza rielaborarla. Questo le rende ideali per informazioni che devono essere precise al 100%.

Quando usare le Q&A

• Prezzi e tariffe — informazioni che devono essere esatte e non approssimate
• Informazioni legali — termini, garanzie, policy contrattuali
• Condizioni di vendita — tempi e costi di spedizione, limitazioni al servizio di consegna, ecc.
• Domande ricorrenti — risposte che vuoi controllare parola per parola

Come creare Q&A efficaci

Ogni Q&A è composta da una domanda e una risposta. La domanda deve essere scritta nel modo più naturale possibile, come la formulerebbe un cliente reale.

Best practice

• Scrivi le domande nel modo più naturale in cui un cliente le farebbe
• Mantieni le risposte concise e dirette
• Consulta la sezione "Da migliorare" per trovare domande reali formulate dagli utenti a cui il bot non sa rispondere bene — sono candidati perfetti per nuove Q&A
• Il pulsante "Svuota tutte le Q&A" rimuove tutte le domande frequenti in una volta (operazione irreversibile)

Knowledge Base — Media

Puoi aggiungere immagini e video alla Knowledge Base. Il bot decide autonomamente quando mostrare un media basandosi sul campo Descrizione e contesto d'uso che associ a ciascun elemento.

Formati supportati

• Immagini — JPG, PNG, GIF, WebP (max 5 MB)
• Video — URL di YouTube, Vimeo o qualsiasi altro URL video pubblico (non puoi caricare file video diretti ma devi utilizzare un servizio di streaming remoto)

Descrizione e contesto d'uso

È il campo più importante: spiega cosa rappresenta il media e quando il bot dovrebbe mostrarlo. Più è dettagliato e specifico, più il bot saprà usarlo nel momento giusto.

Esempio sbagliato: "foto prodotto"

Esempio corretto: "Foto della borsa modello Milano in pelle nera, da mostrare quando il cliente chiede informazioni sulla borsa Milano o vuole vedere meglio come è fatta"

Best practice

• Ogni media deve avere una descrizione unica e specifica
• Usa immagini di buona qualità ma ottimizzate per il web
• Evita immagini duplicate o molto simili
• Per i video, assicurati che i link siano pubblici e accessibili (YouTube, Vimeo o qualsiasi URL video)
• Il pulsante "Svuota tutti i media" rimuove tutte le immagini e video in una volta (operazione irreversibile)

Panoramica

La pagina Panoramica fornisce un riepilogo a colpo d'occhio dell'attività e delle prestazioni del bot. È la prima pagina della sezione Analytics ed è progettata per darti una comprensione rapida di come viene utilizzato il bot e di quanto bene sta funzionando.

Periodo temporale

Puoi filtrare i dati su tre intervalli: 7 giorni, 30 giorni o 90 giorni. Tutte le metriche e i grafici si aggiornano di conseguenza.

Metriche principali

• Conversazioni — numero totale di sessioni di chat nel periodo selezionato
• Media messaggi per sessione — numero medio di messaggi scambiati per conversazione
• Soddisfazione — percentuale di feedback positivi (pollice su vs pollice giù). Codificata a colori: verde (≥ 70%), giallo (≥ 50%), rosso (< 50%)
• Conversione lead — percentuale di conversazioni che hanno generato un lead (visibile solo per i bot pubblici con raccolta lead attiva)

Engagement e funnel

• Durata media — durata media delle conversazioni
• Bounce rate — percentuale di sessioni in cui l'utente ha inviato un solo messaggio (verde ≤ 20%, giallo ≤ 40%, rosso > 40%)
• Tasso di handoff — percentuale di conversazioni in cui l'utente ha richiesto un operatore umano
• Tasso di feedback negativi — percentuale di messaggi che hanno ricevuto un pollice giù

Grafico volume

Un grafico a barre giornaliero mostra il trend del volume di conversazioni nel periodo selezionato, aiutandoti a individuare pattern di utilizzo e picchi di traffico.

E-commerce

• Prodotti mostrati — numero di prodotti distinti proposti dal bot in chat nel periodo, con il totale degli eventi di visualizzazione
• Click — numero di click degli utenti sui prodotti mostrati, con il totale degli eventi
• CTR — click-through rate, ovvero la percentuale di prodotti mostrati che hanno ricevuto un click

Il grafico Andamento prodotti mostra giorno per giorno l'evoluzione di impressioni, click e CTR, per capire quanto i prodotti suggeriti dal bot attirano l'interesse degli utenti.

Performance

La sezione Performance offre una visione completa di come il bot utilizza la sua Knowledge Base. In alto, quattro card riepilogative mostrano le interazioni totali, lo score di confidenza medio e il conteggio dei feedback positivi/negativi. I dati sono organizzati in tre tab.

Da migliorare

Questa tab raccoglie le interazioni in cui il bot ha avuto bassa confidenza nella risposta (score sotto 0.5). Convenzionalmente, uno score fino a 0,3 è considerato negativo, tra 0,3 e 0,5 medio, sopra 0,5 buono.

• Score — più è basso, meno il bot era sicuro. Sotto 0.3 (rosso) la risposta è quasi certamente inadeguata
• Feedback — pollice su/giù lasciato dall'utente, se disponibile
• Fonte — RAG (risposta dalla Knowledge Base), FAQ (risposta esatta da Q&A), o NONE (nessun contenuto trovato)

Clicca su una riga per vedere il dettaglio completo (domanda dell'utente + risposta del bot). Dalla vista di dettaglio puoi:

1. Usare il pulsante "+Q&A" per creare una coppia domanda-risposta mirata che colmi la lacuna
2. Segnare l'interazione come "Risolto" se la risposta del bot era in realtà corretta
3. Segnarla come "Ignora" se la domanda non è rilevante per il bot

Top Q&A

Questa tab mostra le Q&A più utilizzate, classificate per numero di volte in cui ciascuna coppia domanda-risposta è stata usata dal bot. Per ogni voce puoi vedere:

• Domanda e un'anteprima della risposta
• Utilizzi — il numero di volte in cui il bot ha abbinato questa Q&A a una domanda dell'utente
• Ultima modifica — quando la Q&A è stata aggiornata l'ultima volta

È utile per identificare le Q&A di maggior valore e assicurarsi che siano sempre aggiornate.

Top sorgenti KB

Questa tab mostra come il bot utilizza ciascuna sorgente della Knowledge Base, suddivise in tre gruppi:

• Sorgenti più citate — le sorgenti che il bot consulta più spesso per generare le risposte, con il conteggio delle citazioni e lo score di confidenza medio
• Sorgenti non utilizzate — sorgenti che non sono mai state citate in nessuna risposta. Potrebbero contenere contenuti che non corrispondono alle domande degli utenti oppure necessitare di titoli e note migliori
• Sorgenti deboli — sorgenti che vengono citate ma con uno score di confidenza costantemente basso, il che suggerisce che il contenuto potrebbe necessitare di miglioramenti

Prodotti più visti

Per ogni prodotto la tabella mostra:

• Prodotto — nome del prodotto suggerito dal bot
• Impressioni — numero di volte in cui il prodotto è stato mostrato in chat
• Click — numero di click ricevuti dagli utenti
• CTR — click-through rate, ovvero la percentuale di impressioni che hanno generato un click

Puoi ordinare la tabella per ciascuna colonna. L'etichetta "dati scarsi" accanto a un prodotto segnala che le impressioni accumulate sono ancora troppo poche perché il CTR sia statisticamente significativo: il valore va interpretato con cautela finché non si raccolgono più dati.

Best practice

• Controlla questa sezione regolarmente (almeno una volta a settimana)
• Nella tab "Da migliorare", dai priorità alle domande con feedback negativo o score molto basso
• Se vedi la stessa domanda ripetuta più volte, è un segnale forte che manca del contenuto nella Knowledge Base
• Dopo aver creato una Q&A, il bot risponderà correttamente alle occorrenze successive
• Controlla periodicamente le sorgenti non utilizzate: valuta se migliorarne titoli e note, o rimuoverle se non sono più pertinenti
• Usa la tab Top Q&A per assicurarti che le risposte più utilizzate siano sempre accurate e aggiornate

Argomenti

Gli argomenti mostrano quali prodotti, servizi e aree interessano ai tuoi utenti. Il sistema analizza i messaggi e li classifica per soggetto — usando i nomi reali dei tuoi prodotti e servizi, non categorie generiche. Il grafico e la tabella contano le conversazioni, non i singoli messaggi: un utente che fa 5 domande sullo stesso prodotto conta come 1 conversazione.

Come funziona la classificazione

• Quando apri questa pagina, i messaggi non classificati vengono elaborati automaticamente
• I messaggi vengono raggruppati per sessione di conversazione e inviati in batch all'AI, che usa il contesto della conversazione per determinare il soggetto reale
• I messaggi generici (saluti, richieste di contatto, "grazie") vengono classificati sotto il soggetto della loro conversazione, non letteralmente
• L'indicatore verde mostra il progresso della classificazione

Creazione manuale argomenti

Usa il campo sopra la tabella per creare argomenti vuoti con i nomi esatti dei tuoi prodotti, servizi o aree. L'AI li vedrà durante la classificazione e li utilizzerà. Questo è il modo migliore per guidare il sistema — tu conosci il tuo catalogo meglio di quanto l'AI possa scoprire dalle sole conversazioni.

Periodo temporale

Puoi filtrare i dati su 7 giorni, 30 giorni o 90 giorni. Il grafico a ciambella e la tabella si aggiornano per mostrare solo il periodo selezionato.

Gestione argomenti

• Rinomina — clicca l'icona matita per modificare il nome inline
• Nascondi — rimuove l'argomento dal grafico e dalla tabella senza eliminarlo. Utile per argomenti irrilevanti. Gli argomenti nascosti continuano a ricevere nuovi messaggi
• Mostra — apri il pannello "Mostra nascosti" in fondo per ripristinare un argomento nascosto
• Riclassifica — reimposta tutti i messaggi dell'argomento come non classificati. Verranno ri-analizzati e assegnati ad argomenti più specifici alla prossima classificazione. Utile quando un argomento è troppo generico

A cosa serve

Gli argomenti ti aiutano a capire i pattern di domanda dei tuoi utenti: quali prodotti e servizi generano più interesse, se ci sono argomenti emergenti che richiedono nuovi contenuti nella Knowledge Base, e quali aree della tua attività generano più domande.

Cronologia Chat

La cronologia chat mostra tutte le conversazioni avvenute tra gli utenti e il bot. Ogni conversazione è raggruppata in sessioni: una sessione corrisponde a un'interazione completa di un visitatore, dall'apertura alla chiusura del widget.

Come leggere le anteprime

Ogni anteprima mostra una serie di dettagli riguardanti la sessione di chat, tra cui:

• Data e ora dell'ultima interazione
• Numero di messaggi scambiati
• Anteprima dell'ultimo messaggio dell'utente

Cliccando su una sessione puoi leggere l'intera conversazione, messaggio per messaggio, con le risposte del bot e gli eventuali feedback (pollice su/giù) lasciati dall'utente.

Oltre a ciò puoi vedere una serie di dettagli tecnici riguardanti la configurazione del bot al momento della chat, il tono utilizzato, il numero di messaggi scambiati, eventuali feedback positivi/negativi, sorgente delle risposte, ecc.

Scaricare una conversazione

Nella vista di dettaglio di ogni sessione è presente il pulsante "Scarica TXT" che permette di esportare l'intera conversazione in un file di testo (.txt). Il file include tutti i messaggi scambiati tra l'utente e il bot, ed è utile per archiviare, condividere o analizzare le conversazioni offline.

A cosa serve

Consultare la cronologia ti permette di:

• Capire cosa chiedono i visitatori più frequentemente
• Verificare la qualità delle risposte del bot
• Individuare lacune nella Knowledge Base — argomenti su cui il bot non ha informazioni sufficienti e/o non è in grado di rispondere correttamente
• Valutare l'esperienza utente complessiva

Leads

I leads sono i contatti raccolti dal bot durante le conversazioni. Questa sezione è disponibile solo per i bot pubblici. I contatti possono provenire da:

• Form pre-chat — compilato dall'utente prima di iniziare la conversazione
• Form di handoff — compilato quando l'utente richiede di parlare con un operatore e decide di compilare un modulo di ri-contatto
• Raccolta in-chat — il bot chiede i dati di contatto durante la conversazione

Gestione degli stati

IKIbrain include un mini CRM integrato per la gestione dei lead raccolti dal chatbot. Ogni lead ha uno stato che puoi aggiornare direttamente dalla tabella:

• Nuovo — lead appena raccolto, da lavorare
• Contattato — hai già preso in carico e contattato questa persona
• Convertito — il lead si è trasformato in cliente o opportunità
• Perso — lead non interessato o non raggiungibile

Filtri e navigazione

• Usa le frecce per navigare tra i mesi
• Clicca "Tutti" per vedere i leads di tutti i periodi
• Filtra per stato usando i pulsanti sotto il selettore del mese
• L'icona chat a destra apre la conversazione completa del lead

Export CSV

Puoi esportare l'elenco dei lead in formato CSV per importarli nel tuo CRM o per analisi. Il file include tutti i campi raccolti: nome, cognome, email, telefono, azienda, messaggio, stato e data.

Best practice

• Lavora i leads il prima possibile: più tempo passa, meno è probabile convertirli
• Controlla la conversazione del lead prima di contattarlo, per capire cosa cercava e in che modo ha interagito col bot
• Tieni aggiornati gli stati per avere una visione chiara della pipeline

Integrazioni

La pagina Integrazioni raccoglie tutto ciò che serve per collegare il bot al mondo esterno: il codice di embed del Widget, l'API Key e i Webhook.

Le API e i webhook sono due strumenti diversi, anche se spesso lavorano insieme.

• Un’API serve quando un software esterno vuole ricevere o inviare informazioni a IKIbrain. In pratica un sistema esterno può contattare IKIbrain utilizzando l’API Key e inviargli dati in modo sicuro (ad esempio il CMS del tuo sito web può informare il bot quando il contenuto di una pagina viene modificato).
• Un webhook, invece, serve per avvisare automaticamente un altro sistema quando accade un evento all'interno di IKIbrain. In questo caso è IKIbrain che invia i dati verso una piattaforma esterna senza che questa debba fare una richiesta. Ad esempio il sistema può inviare automaticamente i dati di un utente al tuo CRM quando viene acquisito un nuovo lead.

Widget

Per i bot pubblici, IKIbrain fornisce un widget (finestra di chat) che puoi integrare in qualsiasi sito web tramite un semplice codice di embed. Il widget appare come un'icona flottante nell'angolo della pagina e si espande in una finestra di chat quando l'utente ci clicca sopra.

Il sistema di integrazione è universale e funziona su ogni tipologia di sito web.

Come integrare il widget

Nella dashboard del bot o nella pagina Integrazioni trovi il codice di embed: è sufficiente copiarlo e incollarlo nel codice HTML del tuo sito, prima della chiusura del tag </body>. Il widget si caricherà automaticamente in tutte le pagine in cui è presente il codice.

Avanzato: API JavaScript

Il widget espone un'API JavaScript che consente di:

• Nascondere il launcher e aprire la chat solo da bottoni personalizzati
• Aprire con una domanda predefinita e contesto pagina (es. nome prodotto, servizio)
• Aprire / chiudere la chat programmaticamente

Ideale per pagine prodotto e-commerce, annunci immobiliari, pagine servizi e qualsiasi sito dove domande contestuali migliorano l'esperienza utente.

Leggi la guida completa Integrazione Widget

Personalizzazione

Il widget può essere personalizzato in molti aspetti: colori principali, testo del pulsante, messaggio di benvenuto, avatar del bot, posizione nella pagina e molto altro.

API Reference

IKIbrain espone API REST per gestire la Knowledge Base in modo programmatico. Puoi usarle per mantenere i contenuti del bot sincronizzati automaticamente con il tuo CMS o sistema esterno, senza dover agire manualmente nel tuo pannello di controllo.

Autenticazione

Tutte le richieste API richiedono l'API Key del bot nell'header:

Authorization: Bearer YOUR_API_KEY

L'API Key è visibile nella pagina Integrazioni del bot. Puoi rigenerarla in qualsiasi momento se sospetti che sia stata compromessa: la vecchia chiave smette di funzionare immediatamente.

Rate Limiting

Per proteggere il sistema, le richieste sono limitate per API Key:

• 10 richieste/minuto
• 60 richieste/ora

In caso di superamento, la risposta sarà 429 Too Many Requests con il campo retry_after in secondi.

curl -X POST /api/kb/url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/prodotti/widget-pro",
    "description": "Pagina prodotto Widget Pro"
  }'

curl -X PUT /api/kb/url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.example.com/prodotti/widget-pro"}'

curl -X DELETE /api/kb/url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.example.com/prodotti/widget-pro"}'

Integrazione con WordPress

Aggiungi questo snippet al functions.php del tuo tema o in un plugin personalizzato per sincronizzare automaticamente i contenuti:

add_action('publish_post', function ($post_id) {
    $url = get_permalink($post_id);
    wp_remote_request('/api/kb/url', [
        'method'  => 'POST',
        'headers' => [
            'Authorization' => 'Bearer YOUR_API_KEY',
            'Content-Type'  => 'application/json',
        ],
        'body' => json_encode([
            'url'   => $url,
            'force' => true,
        ]),
    ]);
});

add_action('before_delete_post', function ($post_id) {
    $url = get_permalink($post_id);
    wp_remote_request('/api/kb/url', [
        'method'  => 'DELETE',
        'headers' => [
            'Authorization' => 'Bearer YOUR_API_KEY',
            'Content-Type'  => 'application/json',
        ],
        'body' => json_encode(['url' => $url]),
    ]);
});

Integrazione con Zapier, Make, ecc.

Configura un nodo HTTP con:

• URL: /api/kb/url
• Method: POST (o PUT/DELETE)
• Headers: Authorization: Bearer YOUR_API_KEY
• Body: {"url": "...", "force": true}

Sicurezza

• Domini consentiti KB: le API accettano solo URL appartenenti ai Domini consentiti (gestiti dall'amministratore). Se provi ad aggiungere alla Knowledge Base un URL di un dominio non autorizzato, la richiesta viene rifiutata con 403. Se nessun dominio è configurato, l'importazione via API è disabilitata
• Quote: vengono rispettati i limiti di sorgenti e storage del bot
• IP Ban: violazioni ripetute del rate limit comportano un ban progressivo (15 min, 1 ora, 24 ore, 7 giorni)

Webhook

Quando un visitatore compie determinate azioni nel chatbot, IKIbrain può inviare automaticamente una richiesta HTTP POST all'URL che hai configurato, con i dati opportuni in formato JSON.

Questa funzionalità ti consente di far interagire il tuo chatbot con tutto l'ecosistema di applicazioni che utilizzi nel tuo business.

Configurazione

1. Crea un webhook nel tuo strumento di automazione (Zapier, Make, ecc.) e copia l'URL che ti viene fornito
2. Incolla l'URL nel campo "URL Webhook" nella pagina Integrazioni e salva
3. Clicca "Invia webhook di test" per verificare che la connessione funzioni
4. Configura l'azione nello strumento di automazione (es. crea contatto in CRM, riga in Google Sheets, notifica Slack)

Payload JSON

Ogni richiesta webhook contiene questo payload:

{
  "event": "lead.created",
  "bot_id": 42,
  "bot_name": "NomeBot",
  "timestamp": "2026-03-16T14:30:00+00:00",
  "data": {
    "lead_id": 123,
    "first_name": "Mario",
    "last_name": "Rossi",
    "email": "mario@example.com",
    "phone": "+39 02 1234567",
    "company": "Acme Srl",
    "message": "Vorrei informazioni..."
  }
}

I campi in data dipendono da quali informazioni il visitatore ha compilato.

Secret (firma HMAC)

Per maggiore sicurezza, puoi configurare un secret nella pagina Integrazioni. Quando attivo, ogni richiesta webhook include l'header:

X-IKIbrain-Signature: sha256=<hmac_hex>

Il ricevente può verificare l'autenticità calcolando HMAC-SHA256(body, secret) e confrontandolo con il valore nell'header. Per la maggior parte degli strumenti (Zapier, Make, ecc.) il secret non è necessario: l'URL del webhook è già segreto di per sé!

Esempi di integrazione

• Zapier — Trigger "Webhooks by Zapier" → "Catch Hook" → azione su CRM/Sheets/Slack
• Make — Modulo "Webhooks" → "Custom webhook" → router verso i servizi
• n8n — Nodo "Webhook" → nodi di trasformazione e invio
• Albato — Trigger "Incoming Webhook" → configurazione URL → azioni verso CRM, email, fogli di calcolo
• Endpoint custom — qualsiasi server che accetta POST JSON

E-commerce

IKIbrain è progettato per integrarsi con diverse piattaforme e-commerce — WooCommerce, Shopify e IKIshop (il nostro CMS per e-commerce). Collegando il tuo negozio, il bot importa il catalogo prodotti nella Knowledge Base e può rispondere su nome, prezzo, disponibilità e dettagli, oltre a gestire funzionalità avanzate come la consultazione degli ordini.

WooCommerce — Come configurare

Apri la pagina Negozio (menu Connessioni) e compila la Configurazione Negozio:

1. Inserisci l'URL principale del tuo store (es. https://miosito.it), senza slash finale. Se WordPress è installato in una sottocartella usa l'URL completo (es. https://miosito.it/shop). Non includere /wp-json/...: viene aggiunto automaticamente
2. In WordPress vai su WP Admin → WooCommerce → Impostazioni → Avanzate → REST API
3. Crea una nuova chiave con permessi Lettura/Scrittura
4. Copia la Consumer Key (ck_…) e la Consumer Secret (cs_…) negli appositi campi
5. Salva le impostazioni e usa Testa connessione per verificare che sia tutto corretto

Quando la connessione è attiva, un indicatore "Operativa" compare in alto. Il pulsante "Sostituisci credenziali" permette di aggiornare Consumer Key e Secret in un secondo momento senza ridigitarle.

Funzionalità integrate

• Ordini — se attiva, il bot può controllare lo stato di un ordine e lo storico ordini del cliente direttamente in chat

Sincronizzazione real-time

Per ricevere aggiornamenti istantanei da WooCommerce (creazione, modifica ed eliminazione prodotti) senza attendere il sync periodico, puoi configurare un webhook in entrata attivando la Sincronizzazione real-time (sezione opzionale, avanzata). Se non lo configuri, la sincronizzazione automatica continua comunque a funzionare all'intervallo definito.

• URL ricevitore webhook — l'indirizzo a cui WooCommerce invia gli aggiornamenti (es. https://app.ikibrain.ai/api/commerce/webhook/…); copialo con l'apposito pulsante
• Segreto HMAC — firma usata per validare le richieste in arrivo. È conservato in modo sicuro e non è recuperabile: usa "Rigenera segreto" per crearne uno nuovo (l'eventuale webhook esistente va riconfigurato con il nuovo valore)
• Registra webhook su WooCommerce — premendo il pulsante la configurazione sul negozio è automatica. Affinché funzioni, la Consumer Key configurata sopra deve avere permessi di lettura e scrittura

Azioni

Le Azioni permettono al bot di chiamare endpoint HTTP di app esterne (Calendly, Google Calendar, HubSpot, CRM, e-commerce, …) per compiere operazioni concrete durante la chat come prenotazioni, acquisti o invio di email — senza scrivere codice. Un bot può avere più azioni attive contemporaneamente.

Il bot decide autonomamente quale azione invocare in base al flusso della conversazione: raccoglie le informazioni necessarie dall'utente, compila i campi richiesti e chiama l'endpoint al momento giusto. Ad esempio, se un utente chiede di prenotare un appuntamento, il bot raccoglie data e ora preferite e le invia direttamente al calendario senza che l'utente debba uscire dalla chat. Allo stesso modo, se un utente vuole acquistare un prodotto, il bot può guidarlo nella scelta, raccogliere i dati necessari e avviare l'ordine nel sistema e-commerce.

Flusso di conferma

Le azioni mutanti (POST, PUT, DELETE) richiedono conferma per impostazione predefinita. Quando il bot decide di eseguire una di queste azioni, mostra all'utente una card di conferma nel widget con i dettagli dell'operazione. L'utente può confermare o annullare. La conferma è valida per 10 minuti; scaduto questo termine, l'utente dovrà ripetere la richiesta.

Template e azioni custom

Per le integrazioni più comuni sono disponibili template preconfigurati (es. Calendly, Google Calendar, ecc.) ma è possibile anche creare azioni completamente personalizzate. Questo consente di integrare qualsiasi API o sistema esterno che esponga un endpoint HTTP.

Chat Starters

I chat starters sono domande di inizio chat suggerite all'utente, che appaiono come bottoni cliccabili sotto il messaggio di benvenuto. Aiutano l'utente a iniziare la conversazione con un solo clic e gli mostrano il modo corretto di interagire con il chatbot.

Come funzionano

Quando l'utente clicca su uno starter, il testo viene inviato al bot come un normale messaggio, al quale il bot restituisce una risposta. Gli starters scompaiono dopo il primo messaggio inviato.

Configurazione

• Puoi configurare fino a 8 starters
• All'apertura della chat ne vengono mostrati al massimo 4, nell'ordine che stabilisci con le frecce
• Se ne configuri più di 4, vengono mostrati 4 a rotazione casuale ad ogni apertura

Consigli per scrivere buoni starters

• Sii specifico — affronta un argomento concreto e ben delimitato, ad esempio: "Quali sono gli orari di apertura?"
• Sii diretto — poche parole, dritto al punto, senza giri di parole
• Copri le domande frequenti — pensa alle domande che i tuoi utenti fanno più spesso
• Varia gli argomenti — copri aree diverse del tuo sito o servizio

Esempi

• "Quali sono gli orari di apertura?"
• "Come posso prenotare un appuntamento?"
• "Quali servizi offrite?"
• "Ho bisogno di assistenza"

Chat standalone

La chat standalone è una versione del chatbot accessibile tramite un link diretto, senza bisogno di integrare il widget in un sito web. Si apre in una pagina dedicata a schermo intero ed è pensata per tutti quei contesti in cui l'embed non è praticabile o non è necessario.

Come funziona

Ogni bot ha automaticamente un link diretto basato sul suo nome interno (es. /chat/nome-bot). Dalla dashboard puoi ottenere:

• L'URL del bot — un link permanente e leggibile, che puoi condividere liberamente
• Un QR code — scaricabile in formato PNG o SVG, pronto per essere stampato su biglietti da visita, volantini, cartellonistica o qualsiasi altro materiale

Quando usarla

• Condivisione diretta — via email, messaggistica, social media o newsletter
• Materiale stampato — biglietti da visita, brochure, poster, totem con QR code
• Presentazioni e demo — per mostrare il chatbot senza dover accedere a un sito
• Bot privati — è l'unico canale di accesso (il widget non è disponibile per i bot privati)

Bot pubblici vs bot privati

Per i bot pubblici, chiunque abbia il link può avviare una conversazione.

Per i bot privati, la chat standalone rappresenta l'unico punto di accesso. L'utente deve autenticarsi tramite OTP (codice temporaneo via email) prima di poter interagire con il bot.

Chat Links

I Chat Links sono una funzionalità della chat standalone che consente di creare URL con domande preimpostate. Ogni link contiene un token univoco (es. /chat/nome-bot?q=a1b2c3d4e5f6) e, quando l'utente lo apre, la domanda viene inviata automaticamente al bot.

Sono ideali per QR code su volantini, packaging e materiale promozionale: l'utente scansiona, atterra sulla chat standalone e riceve subito la risposta. Puoi modificare la domanda in qualsiasi momento senza cambiare l'URL, così il QR code stampato resta sempre valido.

A differenza dei chat starters, i chat links funzionano esclusivamente con la chat standalone e non hanno effetto sul widget.

Varianti

Una variante è una versione alternativa del tuo bot che condivide la stessa Knowledge Base ma può avere personalità, regole, tono, aspetto grafico e messaggio di benvenuto diversi. Le varianti sono utili quando vuoi usare le stesse informazioni in contesti diversi.

Quando usare le varianti

• Canali diversi — un widget sul sito principale e uno diverso per una linea di prodotti specifica, un landing page o una sezione del sito
• Eventi e fiere — una variante dedicata con tono e messaggio personalizzati per l'evento
• Reparti diversi — assistenza vendite vs assistenza tecnica, con personalità e regole differenti ma la stessa base di conoscenza
• Test A/B — provare toni o stili di risposta diversi sullo stesso set di dati per capire quale funziona meglio

Come funzionano

Ogni variante ha il proprio codice embed per il widget e il proprio link alla chat standalone, che puoi trovare nella pagina Varianti del bot. La creazione e la configurazione delle varianti sono operazioni riservate all'amministratore: non è possibile gestirle autonomamente dal pannello.

Knowledge Base: contenuti condivisi e esclusivi

Per impostazione predefinita, tutti i contenuti della KB sono condivisi: il bot principale e tutte le sue varianti vi accedono. Tuttavia, per quattro tipi di contenuto — Files, Snippet, Q&A e Media — è possibile creare elementi esclusivi di una variante specifica.

• Contenuti condivisi (bot principale) — visibili al bot principale e a tutte le sue varianti
• Contenuti esclusivi (variante) — visibili solo a quella specifica variante; invisibili al bot principale e alle altre varianti

Per creare contenuti esclusivi, usa il selettore "Ambito" in cima alle pagine Files, Snippet, Q&A e Media per selezionare la variante desiderata prima di creare il contenuto. Le Pagine Web non supportano questa funzionalità: appartengono sempre al bot principale e sono accessibili a tutte le varianti.

Chat Starters

Ogni variante può avere i propri chat starters (domande di apertura suggerite). Se una variante non ha starters propri, vengono usati quelli del bot principale come fallback. I chat starters delle varianti si gestiscono dalla pagina Chat Starters, selezionando la variante nel selettore "Ambito".

Cancellazione dei contenuti

I pulsanti "Svuota tutti" nelle pagine KB eliminano tutti i contenuti di quel tipo, compresi quelli esclusivi di tutte le varianti — non solo gli elementi attualmente visibili nella vista filtrata. Controlla sempre attentamente prima di usare questa funzione.

Bot privati

Un bot privato è un chatbot ad accesso riservato: solo gli utenti espressamente autorizzati possono interagire con esso. A differenza dei bot pubblici, un bot privato non dispone di widget da integrare nei siti web e non raccoglie lead.

Come funziona l'accesso

L'unico modo per accedere a un bot privato è tramite il link diretto (chat standalone). Quando un utente apre il link, deve autenticarsi tramite OTP (One-Time Password):

1. L'utente inserisce il proprio indirizzo email
2. Se l'email è presente nella lista degli utenti autorizzati, riceve un codice temporaneo via email
3. Inserisce il codice per accedere alla chat

Se l'email non è nella lista, l'accesso viene negato senza rivelare se l'indirizzo è registrato o meno.

Casi d'uso

• Knowledge base aziendale interna — un assistente AI riservato ai dipendenti, addestrato su documentazione, procedure e policy interne
• Supporto clienti premium — un chatbot dedicato ai clienti con contratto attivo, con accesso a documentazione tecnica riservata
• Formazione — un assistente per corsi o percorsi formativi, accessibile solo agli iscritti
• Consulenza professionale — un bot riservato ai clienti di uno studio professionale, addestrato su normative e documentazione specifica

Differenze rispetto ai bot pubblici

• Nessun widget da integrare nei siti web
• Nessuna raccolta lead o form pre-chat
• L'accesso avviene esclusivamente tramite il link diretto (chat standalone)
• È disponibile la sezione Utenti autorizzati per gestire gli accessi

Utenti autorizzati

Questa sezione è disponibile solo per i bot privati. I bot privati richiedono autenticazione: solo gli utenti espressamente autorizzati possono accedere al chatbot.

Come funziona l'accesso

Quando un utente tenta di accedere a un bot privato, deve autenticarsi tramite OTP (One-Time Password): inserisce il proprio indirizzo email, riceve un codice via email e lo inserisce per accedere. Solo gli indirizzi email presenti nella lista degli utenti autorizzati possono completare l'accesso.

Gestione degli utenti

• Aggiungi utente — inserisci nome ed email dell'utente da autorizzare
• Modifica — puoi aggiornare il nome e l'email associati a un utente
• Rimuovi — revoca l'accesso all'utente (non potrà più autenticarsi)
• Import in blocco — carica un file CSV con l'elenco degli utenti da autorizzare (formato: email,nome — un'email per riga, il nome è opzionale)