FuerteventuraTV AI Chatbot — Documentazione (WordPress)
FuerteventuraTV AI Chatbot è un widget di chat AI flottante e multilingue per WordPress. Aggiunge al tuo sito un assistente che risponde ai visitatori in inglese, italiano o spagnolo, alimentato dalla tua chiave NVIDIA NIM — conservata cifrata sul server, mai esposta al browser — senza alcun costo per messaggio da parte nostra. È l'edizione WordPress gemella di El Savio (la versione Joomla) ed è pensata per siti turistici ed editoriali che ricevono visitatori internazionali con le stesse domande ricorrenti in più lingue.
Requisiti: WordPress 6.0 o superiore, PHP 8.1 o superiore.
Installazione
- Scarica il file
.zipdel plugin dall'email di acquisto o dal tuo account. Non decomprimerlo. - Nella bacheca di WordPress vai su Plugin → Aggiungi nuovo → Carica plugin.
- Seleziona il file zip
fvtv-chatbot, clicca su Installa ora, poi su Attiva. - Dopo l'attivazione, la schermata delle impostazioni del plugin appare nel menu di amministrazione.
Configurazione
Tutte le impostazioni si trovano nella schermata delle impostazioni del plugin nel menu di amministrazione. I passaggi principali dopo l'attivazione:
- Inserisci la tua Download Key. La ricevi con l'email di licenza dopo l'acquisto. Incollala nel campo apposito della schermata delle impostazioni — sblocca gli aggiornamenti con licenza in un clic dal server di aggiornamento GMC / FuerteventuraTV.
- Aggiungi la tua chiave NVIDIA NIM. Il chatbot funziona su NVIDIA NIM con la tua chiave del provider. Inseriscila nelle impostazioni; viene salvata cifrata sul server e non viene mai inviata ai browser dei visitatori. Non c'è alcun costo per messaggio da parte nostra — paghi solo il tuo provider.
- Configura il profilo AI. Imposta il profilo dell'assistente in modo che le sue risposte restino coerenti con il tuo sito.
- Imposta le risposte rapide. Definisci risposte rapide per indirizzare i visitatori verso le conversazioni più comuni.
- Configura il fallback FAQ locale. Le domande comuni gestite dalle FAQ locali non usano alcuna chiamata AI, quindi quelle risposte sono istantanee e non consumano crediti del provider.
- Punta il feed RSS delle notizie ai tuoi contenuti. L'assistente può includere nelle sue risposte i contenuti attuali del tuo sito invece di rispondere nel vuoto.
Il rate limiting sull'endpoint di chat è integrato e lo protegge dagli abusi senza configurazione aggiuntiva.
Uso del plugin
Il widget di chat flottante
Una volta configurato, il widget appare come un pulsante di chat flottante sul frontend del sito. I visitatori possono chattare in inglese, italiano o spagnolo, con cambio di lingua, e il plugin rispetta la configurazione multilingue del tuo sito. Le risposte rapide compaiono nel widget per guidare i visitatori verso le risposte più richieste.
Fallback FAQ e risposte AI
Quando la domanda di un visitatore corrisponde a una voce delle FAQ locali, la risposta viene fornita immediatamente senza alcuna chiamata AI — veloce e senza consumo del provider. Le domande davvero nuove vengono inviate a NVIDIA NIM con la tua chiave. Il plugin funziona anche senza alcuna chiave AI: in quel caso ricade completamente sulle risposte delle FAQ locali, così il widget risponde comunque alle domande comuni.
Endpoint REST
Il widget comunica con il server tramite un endpoint REST su fvtvchatbot/v1/chat. Le richieste sono soggette a rate limit e la chiave del provider resta sempre lato server. Normalmente non hai bisogno di toccare questo endpoint — esiste per il widget stesso.
Aggiornamenti e licenza
Gli aggiornamenti sono automatici. Con la tua Download Key inserita nella schermata delle impostazioni, il plugin controlla autonomamente il server di aggiornamento GMC / FuerteventuraTV (circa ogni 12 ore) e propone le nuove versioni in Plugin e in Bacheca → Aggiornamenti, come qualsiasi altro plugin, finché la tua licenza è attiva. Puoi anche riscaricare in qualsiasi momento l'ultima build dal tuo account.
Il software è rilasciato sotto licenza GNU GPL. L'acquisto (49 EUR, una tantum) ti dà la build ufficiale, gli aggiornamenti con licenza in un clic e il supporto per un sito. Se ti serve su più siti o per progetti di clienti, contattaci per un accordo volume o agenzia. La licenza copre solo il plugin WordPress fvtv-chatbot; l'edizione Joomla (El Savio) e la variante della linea ESE sono prodotti separati.
Supporto
Per assistenza, rispondi alla tua email di acquisto o scrivici su WhatsApp al numero +34 633 168 995 — la stessa linea indicata nella tua email di licenza. Includi:
- il nome e la versione del prodotto,
- le tue versioni di WordPress e PHP,
- un URL pubblico o uno screenshot del problema (con eventuali chiavi oscurate).
Rispondiamo in inglese, italiano e spagnolo. Se il plugin non funziona come descritto e non riusciamo a risolvere il problema, puoi richiedere un rimborso entro 14 giorni dall'acquisto.
Tutto incluso
79 funzionalità reali, raggruppate per area — tutta la profondità del chatbot AI El Savio, distribuito identico per Joomla e WordPress.
Motore di conversazione AI
- 16 dei migliori LLM disponibili da subito — scegli tra Meta Llama 3.1/3.2/3.3/4, NVIDIA Nemotron, Mistral/Mixtral, Google Gemma 3, OpenAI GPT-OSS e Qwen 3, tutti su NVIDIA NIM.
- Bilancia qualità e costo — temperatura configurabile, budget di token massimi, profondità della cronologia conversazione e timeout delle richieste.
- Controllo della lunghezza per risposte complete — una direttiva scalata sul budget di token fa concludere al modello ogni frase ed elenco, invece di interrompersi a metà risposta.
- Endpoint provider personalizzato — punta il client verso qualsiasi URL di chat-completions compatibile con NVIDIA NIM, se usi un instradamento tuo.
- La tua chiave non tocca mai il browser — tutte le chiamate al modello girano lato server, così credenziali e prompt restano privati.
- Memoria multi-turno — la cronologia recente della conversazione viene inserita in ogni richiesta, così le risposte restano nel contesto.
Ancoraggio & conoscenza
- Risposte ancorate ai tuoi contenuti — le risposte restano in linea col brand e in tema, invece di attingere a conoscenze generiche dal web.
- Base di conoscenza personalizzata completa — incolla i tuoi fatti, le tue policy e i dettagli che l'assistente deve conoscere.
- Elenco di servizi / offerte — dichiara esattamente cosa vendi, così il bot promuove offerte reali e sa cosa è fuori menu.
- Persona modificabile — imposta nome, ruolo e personalità dell'assistente, più un blocco di system-prompt aggiuntivo a testo libero.
- Contesto aziendale per pagina — su una pagina profilo di un host (es. tramite com_agentize) il widget risponde su quella specifica attività, ripulita di nuovo lato server.
- Modalità white-label — rinomina l'assistente rimuovendo il brand FuerteventuraTV; il prompt passa a un'identità neutra, interamente guidata da opzioni, con i tuoi contatti e l'URL del sito.
- Matcher di bypass FAQ — le domande configurate ricevono risposta istantanea a zero crediti AI, con corrispondenza contains / exact / regex (limiti PCRE irrobustiti).
- Funziona ancora prima di impostare una chiave AI — FAQ corrispondenti e un fallback localizzato EN/IT/ES mantengono il widget reattivo anche senza chiave provider configurata.
- Contatori di utilizzo FAQ — vedi quali risposte predefinite vengono usate di più, così puoi perfezionarle.
Contesto live (meteo, mare & notizie)
- Meteo live nella risposta — temperatura attuale, vento e raffiche da Open-Meteo (nessuna chiave API extra), in cache e localizzati.
- Condizioni marine — altezza delle onde, direzione, periodo e livello del mare per siti costieri / orientati al surf.
- Orari delle maree automatici — eventi di alta/bassa marea ricavati dalla serie oraria del livello del mare per le prossime 24 h.
- Località configurabile — imposta latitudine, longitudine ed etichetta leggibile; predefinita su Corralejo, Fuerteventura.
- Notizie RSS riassunte nel prompt — fino a tre feed (EN/IT/ES) recuperati lato server, così il bot può indirizzare i visitatori ai tuoi contenuti più recenti.
- Aggiornato ma economico — meteo e notizie hanno ciascuno TTL di cache indipendenti e regolabili dall'admin.
Multilingua & localizzazione
- 11 lingue per il contesto live — contesto di meteo, mare e notizie reso in EN, IT, ES, DE, FR, PT, PL, RU, CS, SK, HR.
- Selettore di lingua nel widget — i visitatori cambiano lingua al volo senza ricaricare la pagina.
- Rilevamento automatico della lingua del visitatore — risolta dal tag lingua del sito (Joomla) o da WPML / Polylang / locale (WordPress), con un valore predefinito configurabile e un'opzione auto.
- Messaggi di benvenuto localizzati — testo di saluto per ogni lingua (lasciandolo vuoto resta il valore predefinito integrato).
- Risposte rapide per lingua — chip di suggerimento cliccabili che guidano le conversazioni più comuni, modificabili per ogni lingua.
Widget di chat & esperienza ospite
- Pulsante di chat fluttuante su ogni pagina — apre un pannello di chat modale con un'animazione fluida.
- Launcher personalizzabile — scegli un'emoji o l'immagine di un logo come avatar, più colori primario/secondario.
- Controllo del posizionamento — angolo in basso a destra o in basso a sinistra.
- Risposte con formattazione ricca — rendering Markdown sicuro contro XSS (grassetto, corsivo, codice inline, titoli, righe, elenchi puntati, link) invece di asterischi grezzi.
- Passaggio dolce a WhatsApp — per prezzi, orari o disponibilità in tempo reale il bot reindirizza al tuo numero WhatsApp configurato invece di inventare dettagli.
- Memoria conversazione con opt-in — la cronologia della chat può persistere nel browser tra le pagine; disattivata di default e cancellata quando la si disabilita.
- Nessuna dipendenza frontend — widget in vanilla-JS, senza jQuery né librerie esterne, sicuro su qualsiasi template.
Acquisizione lead & notifiche
- Non perdere mai la domanda fuori-offerta — il modello segnala le richieste di cose che non vendi (auto a noleggio, hotel, ristorante…) e attiva una notifica invece di finire in un vicolo cieco.
- Avvisi via email — le richieste fuori-offerta vengono inviate a un indirizzo che si precompila con l'email dell'admin, con oggetto configurabile.
- Avvisi via webhook — invia lo stesso avviso a Slack, a un bot Telegram o a qualsiasi endpoint JSON generico.
- Registro delle notifiche — vista admin di sola lettura di ogni avviso con lingua, anteprima del messaggio, IP con hash e flag di invio mail/webhook.
- Limitato e non bloccante — le notifiche hanno un limite di frequenza e non ritardano né bloccano mai la risposta al visitatore.
Amministrazione & operatività
- Dashboard di backend — stato a colpo d'occhio più i contatori delle notifiche aggregati in un'unica query.
- Gestore delle FAQ — creazione/lettura/modifica/eliminazione completa delle risposte predefinite, con lingua e tipo di corrispondenza per ogni voce.
- Test di connessione NVIDIA con un clic — interroga il provider e riporta la latenza più suggerimenti chiari per gli errori 401/402/403/429/503 (con link di risoluzione).
- Endpoint di health — diagnostica protetta da ACL che riporta lo stato di configurazione del provider e dello schema del database senza mai far trapelare la chiave.
- Modalità admin-assistant — con opt-in, il widget gira dentro il backend admin come assistente consapevole della pagina (schermata corrente inoltrata, ri-validata lato server; bloccata sulle schermate utenti/installer/editor/opzioni).
- Permessi granulari — regole ACL standard di Joomla sul componente.
Controlli di visibilità & posizionamento
- Regole di dove mostrarlo — targeting per route/prefisso di percorso, pagina esatta o voci di menu di navigazione specifiche.
- Controllo ovunque-o-da-nessuna-parte — predefinito con wildcard e override per singola pagina.
- Protezione anti-conflitto Vokira — nasconde automaticamente questo chatbot sulle pagine dove viene renderizzato l'add-on concierge premium Vokira, così due assistenti non si sovrappongono mai.
- Blacklist admin rigida — il widget non viene mai iniettato sulle schermate di login, installer, configurazione, gestione utenti o post-installazione.
Sicurezza & privacy
- Chiave API cifrata a riposo — memorizzata con XSalsa20-Poly1305 (libsodium), con chiave derivata dai secret/salt del sito stesso, così il testo cifrato è vincolato a quella installazione.
- Campo chiave mascherato — il blob cifrato non viene mai reso nel browser; "lascia vuoto per mantenere" previene sovrascritture accidentali.
- Protezione CSRF — imposta su ogni endpoint di scrittura.
- Rate limiting atomico per IP — finestre a minuto + ora tramite un singolo upsert SQL privo di race condition; fail-open, così il sito resta attivo anche se il DB cade.
- Rilevamento IP resistente allo spoofing — gli header proxy (Cloudflare / nginx) sono onorati solo per i CIDR di proxy fidati in whitelist.
- Output sicuro contro le injection — una whitelist di URL http/https sull'output del modello e sui link RSS blocca i payload
javascript:/data:. - Parsing XML irrobustito — il parser RSS elimina l'espansione delle entità (mitigazione XXE / billion-laughs) e impone il no-network.
- Header di sicurezza integrati — X-Content-Type-Options, X-Frame-Options, Referrer-Policy e Permissions-Policy sulle pagine frontend (non distruttivi, non sovrascrivono mai i valori del server).
- Builder CSP completo — modalità off / report-only / enforce, sorgenti extra per direttiva script/style/img/connect, report URI opzionale e un toggle unsafe-inline.
- Blocco dell'accesso al manifest — il file
.htaccessinstallato nega l'accesso HTTP ai file XML/INI del plugin. - Rispettoso del GDPR by design — i visitatori devono confermare l'informativa sulla privacy prima del primo messaggio; la persistenza della conversazione è a opt-in; nessun dato è venduto o condiviso con il fornitore.
- Informativa privacy personalizzata — testo di consenso e link alla privacy-policy configurabili dentro il widget, ricordati per ogni host così non vengono richiesti di nuovo a ogni pagina.
Prestazioni & caching
- Scorciatoia FAQ che risparmia crediti — le domande comuni risolte senza alcuna chiamata AI.
- Contesto live in cache — meteo e notizie sono in cache con TTL indipendenti per ridurre le chiamate a monte.
- Dashboard a singolo round-trip — i contatori delle notifiche aggregati in un'unica istruzione SQL.
- Distribuzione via Web Asset Manager — CSS/JS registrati attraverso la pipeline degli asset del CMS con cache-busting per versione, senza tag duplicati.
- Tabella di rate auto-pulente — le righe scadute vengono rimosse in modo probabilistico, senza bisogno di cron.
Sviluppatori & API
- Endpoint di chat JSON pubblico —
chat.send(task Joomla) /POST /wp-json/fvtvchatbot/v1/chat(WordPress). - Endpoint di notizie pubblico —
news.get/GET /wp-json/fvtvchatbot/v1/news, con bypass della cache disabilitato per i chiamanti. - Endpoint di health diagnostico — sonda di stato protetta da ACL su entrambe le piattaforme.
- Filtro di render per WordPress —
fvtv_chatbot_should_renderper nascondere il widget in modo programmatico (es. in fase di checkout). - Filtro di fallback per WordPress —
fvtv_chatbot_pre_key_fallbackper i siti white-label, per sovrascrivere le risposte FAQ offline. - Core testato con unit test — le suite PHPUnit coprono la parità crypto, il matcher FAQ, il rate limiter, il prompt builder e la bussola del meteo; la matrice CI gira su PHP 8.2/8.3/8.4 con phpcs + phpstan.
Affidabilità & licenza
- GPL v2 o successiva — il codice è libero / open-source; mantieni pieni diritti GPL.
- Self-hosted, nessun servizio di chat di terze parti — le conversazioni passano attraverso il provider che configuri; nulla viene instradato tramite il fornitore.
- Porta la tua chiave NVIDIA NIM — idonea al piano gratuito, quindi da noi non c'è alcun costo per messaggio.
- Aggiornamenti con un clic sotto licenza — le nuove versioni si installano direttamente dal backend del CMS tramite il gateway GMC / FuerteventuraTV finché la tua licenza è attiva (Joomla controlla ~ogni 24 h, WordPress ~ogni 12 h).
- Distribuzione aggiornamenti validata — un pacchetto di aggiornamento viene accettato solo quando il gateway restituisce un
download_urlHTTPS valido su fuerteventuratv.net. - Modello Download Key — una chiave dalla email della tua licenza sblocca gli aggiornamenti; riscarica la build più recente dal tuo account in qualsiasi momento.
- Supporto & rimborso — supporto in EN/IT/ES via email o WhatsApp; rimborso entro 14 giorni se non funziona come descritto e non può essere risolto.
- Collaudato in produzione — risponde ogni giorno a visitatori reali sul portale turistico fuerteventuratv.net.
Joomla & WordPress
- Joomla — distribuito come un unico pacchetto
pkg_fvtvchatbot(componentecom_fvtvchatbot+ plugin di sistemaplg_system_fvtvchatbot); interfaccia del widget disponibile in tutte le 11 lingue; richiede Joomla 5.1+ / 6.x e PHP 8.2+. Installa solo lo zip del singolo pacchetto — mai gli zip interni. - WordPress — singolo plugin
fvtv-chatbot; l'interfaccia del widget è distribuita in EN/IT/ES con parità completa del system-prompt a 11 lingue e del pacchetto UI aggiunta nella 1.0.24; si integra con WPML/Polylang per il rilevamento automatico della lingua; chiave API cifrata a partire dai salt di WP; richiede WordPress 6.2+ e PHP 8.2+. Le due build sono mantenute in lockstep come gemelle a parità di funzionalità (meteo/mare, notifica fuori-offerta, motore FAQ, modalità admin-assistant, controlli di visibilità e protezione Vokira presenti su entrambe).
