Chatbot Pilot

Chatbot Pilot è un chatbot AI di customer support per WordPress. Si presenta come un widget chat fluttuante sul frontend e un’area di amministrazione completa in Impostazioni → Chatbot Pilot. Il plugin offre due modalità operative:

• Modalità n8n — il widget inoltra ogni messaggio del visitatore a un workflow n8n  esterno tramite webhook. Usala quando hai già automazioni, logica custom o integrazioni di terze parti fuori da WordPress.
• Modalità RAG nativa — il plugin indicizza i contenuti del tuo sito (post, pagine, custom post type) in chunk memorizzati in un database SQLite locale, recupera i passaggi più rilevanti al momento della query e genera una risposta con il provider LLM che scegli (OpenAI, Anthropic Claude, Google Gemini, DeepSeek o una istanza Ollama self-hosted).

Entrambe le modalità condividono lo stesso widget, lo stesso log conversazioni e gli stessi strumenti di feedback/export, così puoi cambiare backend in qualsiasi momento senza perdere l’esperienza lato visitatore.

Punti di forza

• Dual backend: webhook n8n o Retrieval-Augmented Generation completamente nativa.
• Supporto multi-provider LLM: OpenAI, Anthropic Claude, Google Gemini, DeepSeek, Ollama (locale).
• Motore RAG nativo con storage SQLite, chunk size configurabile e retrieval top-K.
• Indicizzazione in background tramite cron WordPress, così il re-index non blocca mai l’UI admin.
• Widget personalizzabile: posizione, colori primario/sfondo/testo, colori delle bubble utente e bot, dimensioni, border radius, tipografia.
• Copy editabile per messaggio di benvenuto, sottotitolo, placeholder dell’input, stato di caricamento e messaggio d’errore.
• Log conversazioni con feedback per messaggio (pollice su / pollice giù) ed export CSV.
• Health check integrato che verifica connettività dei provider, stato dell’indice e raggiungibilità del webhook.
• Pronto al multilingua tramite Polyglot — copy del widget e knowledge base possono essere serviti per lingua.

Requisiti

Il plugin è self-contained e in modalità RAG nativa non richiede alcun servizio esterno oltre all’API LLM scelta. Il vector store incluso usa SQLite, disponibile in ogni build PHP standard.

Per la modalità n8n serve in più una istanza n8n raggiungibile con un Webhook node configurato per accettare POST. Per Ollama serve un server Ollama in esecuzione e raggiungibile dall’host WordPress (tipicamente http://localhost:11434).

Installazione

1. Apri Plugin → Aggiungi nuovo → Carica plugin nell’admin WordPress e carica il file ZIP di Chatbot Pilot.
2. Attiva Chatbot Pilot.
3. Apri Impostazioni → Chatbot Pilot. Al primo caricamento il plugin crea le sue tabelle e le opzioni di default.
4. Scegli la modalità backend (n8n o RAG nativa) e completa la configurazione del provider qui sotto.
5. In modalità RAG nativa, clicca Reindex almeno una volta per popolare la knowledge base prima di esporre il widget ai visitatori.
6. Visita una qualsiasi pagina pubblica sul frontend per confermare che il widget appaia nella posizione configurata.

Il widget viene enqueue automaticamente su ogni pagina una volta configurato il plugin; non serve nessuno shortcode o modifica al tema.

Configurazione

La schermata impostazioni vive sotto Impostazioni → Chatbot Pilot ed è divisa in sei tab — Generale, AI / RAG, Aspetto, Icone, Testi e Feedback. Tutti i valori sono salvati per sito (o per sito-network su multisite) e si possono cambiare senza re-indicizzare, eccetto i parametri di indicizzazione stessi.

Generale

La tab Generale porta tre card:

• Licenza — incolla la chiave PILOT-XXXX-XXXX-XXXX-XXXX e premi Verifica & Salva per abilitare gli aggiornamenti automatici del plugin.
• General → Enable Chatbot — toggle master che mostra il widget sul sito.
• Visibility → Hidden on these URLs — lista separata da virgole o newline di path su cui il widget deve restare nascosto (match per prefisso: /login nasconde anche /login/).
• Balloon Notification — fa apparire un balloon di hint accanto alla bubble della chat dopo un delay configurabile (Show After in secondi, 0 = subito) per attirare attenzione.

Modalità backend

Scegli esattamente un backend. La scelta determina quali campi successivi sono visibili.

• Webhook n8n — il widget fa POST del messaggio del visitatore, dell’ID conversazione e dell’URL di pagina corrente al webhook che fornisci. La risposta attesa è un payload JSON con una stringa reply che viene renderizzata all’utente.
• RAG nativa — la richiesta è gestita in-process. Il plugin recupera i top-K chunk più rilevanti dall’indice locale, costruisce un prompt e chiama il provider LLM configurato.

Impostazioni n8n

Visibili solo quando la modalità backend è impostata su Webhook n8n.

• Webhook URL — URL HTTPS completo del tuo Webhook node n8n.
• Header di autenticazione (opzionale) — nome e valore di un header da inviare a ogni richiesta, utile per webhook protetti da shared secret.
• Timeout — tempo massimo, in secondi, di attesa di una risposta prima di mostrare il messaggio d’errore all’utente.

AI provider (RAG nativa)

Visibile solo quando la modalità backend è impostata su RAG nativa.

Seleziona un provider e compila i campi corrispondenti:

Ogni provider espone gli stessi tre campi:

• API key (o URL base per Ollama) — memorizzata nella tabella options di WordPress; mai esposta al frontend.
• Modello — l’identificatore di modello specifico da chiamare (per esempio gpt-4o-mini, claude-3-5-sonnet, gemini-1.5-flash, deepseek-chat, llama3.1:8b).
• Test connection — manda un ping minimo al provider e riporta successo o l’errore verbatim restituito dall’API. Lancialo sempre dopo aver cambiato chiave o modello.

Knowledge base

Controlla come l’indice RAG nativo viene costruito e interrogato. Le modifiche ai parametri di chunking hanno effetto al prossimo reindex.

• Source path — lista separata da virgole di post type (o un URL root) da ingest. Lascia il default post,page per indicizzare tutto il sito, o restringi a un CPT specifico di knowledge base.
• Chunk size — numero di token di ciascun chunk scritto nell’indice. Default 500. Chunk più piccoli migliorano la precisione del retrieval; più grandi preservano più contesto.
• Top-K — numero di chunk recuperati per ogni domanda del visitatore e passati all’LLM come contesto. Default 5.
• Reindex — schedula una ricostruzione completa via WP-Cron. La progress bar mostra documenti in coda, processati e saltati. Mentre il job gira, l’indice esistente continua a servire le query.
• Clear index — droppa ogni riga dalla tabella vettoriale. Usalo prima di cambiare modello di embedding.

Aspetto

Ogni aspetto visivo del widget è editabile da questa tab. L’anteprima live a destra si aggiorna immediatamente al variare dei valori.

Posizione

• Bottom-right (default)
• Bottom-left

Colori

• Colore primario — sfondo dell’header, pulsante invia, focus ring.
• Colore di sfondo — sfondo della finestra di chat.
• Colore del testo — colore di testo base dentro la finestra.
• Colore messaggio utente — sfondo della bubble del visitatore.
• Colore messaggio bot — sfondo della bubble dell’assistente.

Dimensioni

• Larghezza e altezza della finestra — in pixel.
• Dimensione del launcher button — diametro del pulsante fluttuante.
• Border radius — applicato alla finestra, alle bubble e al launcher.

Tipografia

• Font family — di default eredita dal tema; può essere sovrascritto con qualunque CSS font stack.
• Font size base — applicato al body della chat.

Icone

La tab Icone disaccoppia il branding dalla tab Aspetto, così puoi cambiare le icone di launcher, chiusura e invio senza toccare colori o dimensioni. Il set incluso copre i pattern chat più comuni; il campo Custom URL accetta qualsiasi SVG o PNG raggiungibile pubblicamente.

Testi

Ogni stringa rivolta al visitatore vive nella tab Testi, così puoi tradurre o riformulare il widget senza toccare il tema visivo:

• Messaggio di benvenuto — primo messaggio mostrato quando un visitatore apre il widget.
• Sottotitolo — testo piccolo sotto il titolo nell’header.
• Placeholder input — testo mostrato nel campo vuoto.
• Testo di caricamento — mostrato in attesa della risposta dell’assistente.
• Messaggio d’errore — mostrato quando la chiamata al backend fallisce o va in timeout.
• Prompt di feedback — testo mostrato sopra ai controlli pollice su / pollice giù (quando il feedback è abilitato).
• Testo Balloon Notification — copy mostrato nel balloon di hint.

Regole di visibilità

• Mostra su — scegli tra Tutte le pagine, Solo sulle pagine selezionate, o Ovunque tranne pagine selezionate. Gli ID pagina si inseriscono come lista separata da virgole.
• Nascondi agli utenti loggati — spegne il widget per le sessioni autenticate.
• Breakpoint mobile — larghezza di viewport sotto cui il widget collassa a layout compatto.

Feedback & analytics

• Abilita pulsanti feedback — aggiunge controlli pollice su / pollice giù sotto ogni messaggio dell’assistente.
• Memorizza conversazioni — tiene la trascrizione completa nella tabella wp_chatbotpilot_conversations per review ed export.
• Periodo di retention — numero di giorni dopo i quali le conversazioni memorizzate vengono cancellate dal cron giornaliero. Imposta 0 per tenerle per sempre.

Health check

Il pannello di health check è sempre visibile in cima alla schermata impostazioni. Lancia tre probe e mostra un pill di stato colorato per ciascuna:

• Raggiungibilità del provider — chiama l’API LLM con un ping di un token.
• Stato dell’indice — conta i chunk nello store SQLite e riporta il timestamp dell’ultimo reindex riuscito.
• Raggiungibilità del webhook (modalità n8n) — manda una richiesta OPTIONS all’URL webhook configurato.

Qualsiasi stato non verde è cliccabile ed espone l’errore verbatim restituito dalla chiamata sottostante, di solito sufficiente per diagnosticare.

Utilizzo

Per i visitatori

Il widget appare su ogni pagina dove le regole di visibilità lo permettono. Il visitatore clicca il launcher button per aprire la finestra, legge il messaggio di benvenuto e scrive una domanda nell’input. Premendo Invio o il pulsante invia, il messaggio parte; il widget mostra il testo di caricamento, poi renderizza la risposta dell’assistente con formattazione markdown (grassetto, link, liste numerate e puntate, code block).

Se i pulsanti di feedback sono abilitati, il visitatore può valutare ogni risposta. Il rating è memorizzato contro l’ID del messaggio così la stessa risposta può essere rivista in seguito nel pannello admin.

Per gli amministratori

L’amministrazione quotidiana avviene in due posti:

• Impostazioni → Chatbot Pilot per la configurazione e il pannello health check.
• Chatbot Pilot → Conversazioni per il log conversazioni e l’export dei feedback.

Il log conversazioni elenca ogni sessione con la data, la pagina di origine, il numero di messaggi e il feedback aggregato. Ogni riga si può espandere per mostrare la trascrizione completa, inclusi i passaggi di contesto recuperati in modalità RAG nativa. Il pulsante Export CSV in cima alla lista produce un CSV UTF-8 con una riga per messaggio; rispetta qualunque filtro per data o rating attivo.

Reindex dopo modifiche al contenuto

L’indice nativo non si aggiorna in tempo reale. Lancia un reindex quando:

• Pubblichi o editi sostanzialmente un batch di post.
• Cambi chunk size, source path o modello di embedding.
• Il pannello health check riporta indice stale o vuoto.

Per aggiornamenti incrementali il plugin ricalcola anche l’indice di un singolo post al salvataggio, se è abilitata l’opzione Auto-reindex on save nella tab Knowledge Base. Aggiunge un piccolo overhead a ogni salvataggio ma tiene la knowledge base allineata senza intervento manuale.

Cambiare backend

Puoi passare tra n8n e RAG nativa in qualsiasi momento. Widget, log conversazioni e archivio feedback sono condivisi tra le modalità. Quando passi a RAG nativa per la prima volta, ricordati di lanciare Reindex prima che il widget possa rispondere alle domande.

Screenshot

Gli screenshot qui sotto corrispondono alle quattro aree principali dell’interfaccia admin e al widget frontend.

Widget chat frontend

Configurazione AI provider

Editor aspetto del widget

Log conversazioni ed export feedback

FAQ

Quale backend dovrei scegliere?

Usa RAG nativa se l’obiettivo è rispondere a domande sui contenuti del tuo sito e vuoi una soluzione self-contained che richieda solo una API key LLM. Usa n8n se devi combinare il chatbot con strumenti esterni (lookup CRM, ticketing, routing custom) o se la conversazione deve scatenare azioni fuori da WordPress.

Devo installare n8n per usare il plugin?

No. n8n serve solo se scegli n8n come modalità backend. La modalità RAG nativa è completamente self-contained.

I miei dati vengono mandati a terze parti?

In modalità RAG nativa ogni prompt e il contesto recuperato sono mandati al provider LLM selezionato. Se non è accettabile, fai girare il plugin contro un’istanza Ollama locale — in quel caso nessun dato lascia il server. In modalità n8n ogni messaggio è mandato al tuo endpoint n8n; cosa succede dopo dipende dal workflow che costruisci.

Dove è memorizzato l’indice?

L’indice vettoriale è un file SQLite in wp-content/uploads/chatbot-pilot/. La tabella options di WordPress contiene la configurazione del chatbot, e la tabella wp_chatbotpilot_conversations contiene il log conversazioni.

Posso usarlo su un sito multilingua?

Sì. Con Polyglot installato, l’indexer ingerisce le versioni tradotte di ciascun post e il copy del widget viene servito per lingua. Senza Polyglot puoi comunque tenere un widget per lingua limitando il source path a categorie language-specific.

Supporta custom post type?

Sì. Aggiungi gli slug dei CPT al campo Source path separati da virgole, e fai reindex.

Posso esportare le conversazioni?

Sì. Il pulsante Export CSV sulla schermata Conversazioni produce un file CSV UTF-8 con una riga per messaggio, incluso rating, timestamp, pagina di origine e testo completo del messaggio.

Come cancello i dati di un visitatore?

Apri Chatbot Pilot → Conversazioni, filtra per session ID o per IP e usa l’azione Delete sulle righe corrispondenti. La conversazione e i suoi feedback vengono rimossi immediatamente.

Il widget funziona senza JavaScript?

No. Il widget è un componente JavaScript single-page; non degrada con grazia a un fallback noscript.

Troubleshooting

Il widget non appare sul frontend

• Verifica che la modalità backend sia impostata e che le credenziali rilevanti (API key o webhook URL) siano salvate.
• Controlla le regole di visibilità — la pagina potrebbe essere esclusa.
• Ispeziona la console del browser: una risposta 4xx da admin-ajax.php di solito indica un problema di permessi o nonce causato da un cache plugin aggressivo.

L’assistente risponde con il messaggio d’errore

Apri il pannello health check e clicca sulla pill rossa per leggere l’errore del provider verbatim. Cause comuni:

• API key scaduta o revocata.
• Il modello selezionato non è disponibile per il tuo account o regione.
• Rate limit superato — aspetta o passa a un piano superiore.
• Il webhook URL restituisce uno status non-2xx.

Il reindex sembra bloccato

Il cron di WordPress scatta solo quando il sito riceve traffico. Triggera un hit di pagina manualmente, oppure chiama wp cron event run --due-now da WP-CLI. La progress bar si aggiorna ogni pochi secondi mentre il job gira.

Le risposte sono off-topic o allucinate

• Fai reindex dopo modifiche recenti al contenuto.
• Alza Top-K per dare più contesto al modello.
• Riduci la Chunk size per un retrieval più granulare, poi fai reindex.
• Prova un modello più potente (per esempio passa da GPT-4o-mini a GPT-4o, o da Gemini Flash a Gemini Pro).

Le risposte di Ollama sono molto lente

La velocità dell’inferenza locale dipende interamente dall’host. Usa un modello quantizzato (:q4_K_M o simile), assicurati che l’accelerazione GPU sia attiva, e tieni chunk size e top-K moderati.

Le conversazioni non vengono memorizzate

Conferma che Store conversations sia abilitato nella tab Feedback & analytics e che la tabella wp_chatbotpilot_conversations esista. Disattivare e riattivare il plugin ricrea le tabelle mancanti.