AI Chat Widget: guida all'uso

Che cos'è AI Chat Widget?

AI Chat Widget è un assistente chat che si esegue sul proprio server e si inserisce in qualsiasi sito web con una sola riga di codice. Risponde alle domande dei visitatori tramite il provider IA scelto, sulla base delle informazioni che Lei gli fornisce, e può raccogliere richieste di contatto quando non è in grado di aiutare.

Tutto risiede sul Suo hosting: il pannello di amministrazione, le conversazioni, la base di conoscenza e le chiavi IA. Nulla viene inviato a noi. L'unico traffico verso l'esterno avviene tra il Suo server e il servizio IA scelto, e tra il browser del visitatore e il Suo server.

Che cosa si può fare

• Collegare qualsiasi provider IA: OpenAI, Anthropic, Google Gemini, Mistral, Groq, Perplexity, OpenRouter, xAI, Together AI, Azure OpenAI, Cohere, LM Studio, Ollama, oppure qualsiasi servizio che si descrive da sé in pochi campi.
• Creare più bot, ciascuno con il proprio argomento, aspetto, testi, regole ed elenco di siti web.
• Istruire un bot con una base di conoscenza: testo incollato, elenchi di domande e risposte, file TXT, Markdown, CSV, HTML, PDF e Word, pagine web e intere sitemap.
• Permettere ai visitatori di lasciare i propri dati di contatto quando il bot non sa rispondere, e ricevere un'e-mail per ogni richiesta.
• Leggere ed esportare le conversazioni, valutare le risposte e consultare le statistiche per capire che cosa chiedono davvero i visitatori.
• Proteggere tutto con l'accesso a due fattori, un registro di controllo completo, elenchi di accesso per sito web, limiti di frequenza e budget giornalieri di token.
• Lavorare in sei lingue: inglese, polacco, tedesco, francese, italiano e spagnolo, sia nel pannello sia nel widget.

Come funziona

Quattro elementi, da configurare in quest'ordine: un provider, un bot, il codice di incorporamento e, infine, ciò che i visitatori dicono davvero.

1. 1
   Provider IA. Una connessione salvata a un servizio IA: il suo indirizzo, il modo di autenticarsi (la Sua chiave API) e il modo di leggerne la risposta. I profili integrati coprono i servizi più diffusi; è possibile aggiungerne di propri.
2. 2
   Bot. Un assistente chat. Ha un provider e un modello, una descrizione del compito (argomento, ambito, tono), un aspetto, dei testi e delle regole. Si possono usare tanti bot quanti ne consente la licenza, per siti web o scopi diversi.
3. 3
   Codice di incorporamento. Una singola riga <script> che inserisce la chat in una pagina (oppure un piccolo plugin WordPress che lo fa al posto Suo).
4. 4
   Conversazioni. Ogni messaggio del visitatore arriva prima al Suo server. Il server verifica le regole, costruisce le istruzioni per l'IA, interroga il provider e restituisce la risposta. La chiave IA non raggiunge mai il browser del visitatore.

Che cosa accade quando un visitatore invia un messaggio

1. 1
   Il widget invia il messaggio a api.php sul Suo server.
2. 2
   Il server verifica che il sito web sia nell'elenco consentito del bot e applica il limite di frequenza, le parole bloccate e il budget giornaliero di token.
3. 3
   Cerca nella base di conoscenza gli estratti pertinenti (se il bot la utilizza) e costruisce le istruzioni: argomento, ambito, tono, informazioni aziendali, estratti e regole di sicurezza sempre attive.
4. 4
   Interroga il provider IA (e un provider di riserva se il primo non risponde).
5. 5
   Salva lo scambio secondo la modalità di registrazione del bot e restituisce la risposta, con i link alle fonti quando il modello li fornisce.

Requisiti di sistema

Installazione

L'installazione richiede pochi minuti e funziona su un normale hosting condiviso, su un VPS o su un server dedicato. Sul server non servono Composer né la riga di comando.

1. 1
   Copiare i file. Carichi l'intera cartella ai-chat-widget nella root web o in una qualsiasi sottocartella. L'indirizzo viene rilevato automaticamente, quindi il nome della cartella non ha importanza.
2. 2
   Creare un database MySQL vuoto nel pannello di controllo del proprio hosting (ad esempio cPanel o DirectAdmin: «Database MySQL»), insieme a un utente del database con tutti i privilegi su di esso. Annotare host (spesso localhost), nome del database, utente e password; verranno richiesti dal programma di installazione.
3. 3
   Aprire il programma di installazione. Vada su https://your-site/ai-chat-widget/install/ e scelga la lingua dell'installazione (inglese, polacco, tedesco, francese, italiano o spagnolo).
4. 4
   Compilare il modulo. Host, nome, utente e password del database, un prefisso per le tabelle (va bene quello predefinito acw_) e il primo amministratore: nome, e-mail e una password di almeno 12 caratteri.
5. 5
   Concludere. Il programma crea le tabelle, scrive config/config.php e un file di blocco, e mostra un link alla pagina di accesso.
6. 6
   **Eliminare la cartella install/** dal server quando viene richiesto.

Aggiornamento

Carichi i nuovi file sopra quelli vecchi (conservando config/ e storage/), acceda e apra Info di sistema. Se il database richiede modifiche, la pagina le elenca; prema Applica aggiornamenti una sola volta. Per la procedura completa veda "Manutenzione".

Primo accesso e dashboard

Acceda con l'e-mail e la password impostate durante l'installazione. Il pannello ricorda la Sua lingua e funziona allo stesso modo su smartphone.

Il menu a sinistra è raggruppato per attività:

La dashboard mostra il piano di licenza, se l'accesso a due fattori è attivo, quanti utenti e bot sono presenti, oltre agli avvisi: aggiornamenti del database in sospeso, un'estensione PHP mancante o le notifiche "2FA richiesta". La barra superiore contiene il menu del profilo (profilo, accesso a due fattori, uscita); la freccia in fondo al menu lo riduce alle sole icone.

Le piccole icone "?"

Ogni campo dei moduli ha un'icona "?" che apre una breve spiegazione. Possono essere disattivate per tutti in Impostazioni > Generale o solo per Lei in Il mio profilo.

Avvio rapido: il primo bot in 8 passaggi

Da un'installazione vuota a una chat sulla Sua pagina, passo dopo passo.

1. 1
   Aggiungere un provider IA. Vada su Provider IA, apra un profilo già pronto (ad esempio OpenAI) e incolli la Sua chiave API. Il link "Ottieni una chiave API" sotto il campo apre la pagina del provider in cui si crea la chiave.
2. 2
   Verificare la connessione. Nello stesso editor prema Recupera modelli, poi usi la console di prova: scelga un modello, invii un messaggio e controlli che arrivi una risposta. Corregga qui la chiave prima di creare un bot.
3. 3
   Creare un bot. Vada su Bot > Aggiungi bot. Gli dia un nome, scelga il provider e il modello e, nella scheda Argomento e prompt, descriva di che cosa deve parlare: la Sua attività, il tono, ciò a cui non deve rispondere.
4. 4
   Impostare aspetto e testi. Schede Aspetto, Comportamento, Testi e Branding: colori, posizione, saluto e domande suggerite. La scheda Chat di prova e "Anteprima del prompt finale" permettono di conversare con il bot direttamente nel pannello.
5. 5
   Consentire il Suo sito web. Nella scheda Sicurezza aggiunga il Suo sito a Siti consentiti (ad esempio example.com o *.example.com). La chat si carica solo sui siti elencati.
6. 6
   Incorporarlo. Apra la scheda Incorporamento, copi lo script di una riga e lo incolli prima di </body> nelle Sue pagine. Su WordPress, scarichi invece il piccolo plugin dalla stessa scheda.
7. 7
   Facoltativo: aggiungere conoscenza e richieste di contatto. Aggiunga documenti in Base di conoscenza, oppure attivi Richieste di contatto sul bot (configuri prima Impostazioni > E-mail).
8. 8
   Osservare e ottimizzare. Chatti con il bot sulla Sua pagina. In seguito consulti Conversazioni e Statistiche, decida che cosa viene salvato (scheda Privacy) e migliori il prompt dove le risposte non sono state utili.

Provider IA

Un profilo provider indica all'applicazione come comunicare con un servizio IA. I profili sono dati, non codice: un servizio nuovo o insolito si può aggiungere senza attendere un aggiornamento.

Profili integrati

OpenAI, Anthropic (Claude), Google Gemini, Mistral, Groq, Perplexity, OpenRouter, xAI (Grok), Together AI, Azure OpenAI, Cohere, LM Studio e Ollama (entrambi locali), più un profilo generico compatibile con OpenAI che può essere indirizzato a qualsiasi server compatibile. Ognuno è pronto all'uso: lo apra, incolli la chiave, salvi.

Aggiungere la chiave

Apra un provider e compili Chiave API. La chiave viene salvata cifrata e non viene più mostrata (solo gli ultimi quattro caratteri). Un messaggio verde conferma che una chiave è salvata; nelle modifiche successive lasci il campo vuoto per conservarla. Il link Ottieni una chiave API accanto al campo porta alla pagina in cui il provider rilascia le chiavi.

La console di prova

Sotto il modulo, la console invia un messaggio reale con il profilo così com'è in questo momento nell'editor, salvato o meno. Mostra la risposta, il tempo, il numero di token e, in caso di errore, la richiesta e la risposta esatte (con la Sua chiave mascherata). La usi ogni volta che modifica un profilo.

Modificare un profilo

Aggiungere un servizio non presente nell'elenco

Duplichi il profilo compatibile con OpenAI (molti servizi parlano quel protocollo) oppure parta da un profilo simile e modifichi indirizzo, intestazioni e percorsi. La console di prova indica che cosa correggere. I profili si possono esportare e importare come file JSON, così è possibile condividerne uno funzionante.

Sicurezza integrata

Ogni chiamata passa attraverso un controllo dell'indirizzo che blocca le reti private, gli indirizzi link-local e quelli dei metadati cloud (a meno che per quel profilo non siano consentite le reti private), rifiuta i reindirizzamenti, limita dimensione e durata della risposta e non scrive mai la Sua chiave nei log o nei messaggi di errore.

Bot

Un bot è un assistente chat. Il suo editor è organizzato in schede e ogni campo ha un'icona di aiuto "?". Salvi una sola volta alla fine; se lascia la pagina, le modifiche non salvate vengono segnalate.

Generale

Argomento e prompt

Si compila un modulo invece di scrivere un prompt. L'applicazione assembla attorno ai Suoi testi un insieme collaudato di istruzioni e aggiunge sempre regole di sicurezza non rimovibili.

Anteprima del prompt finale mostra esattamente ciò che il modello riceverà, comprese le regole di sicurezza.

Modello

Aspetto

Colore principale (il colore del testo si adatta automaticamente), tema chiaro, scuro o automatico, posizione (a sinistra o a destra), distanze dal bordo, dimensione della finestra, arrotondamento degli angoli, icona ed etichetta del pulsante, immagine avatar e, per utenti esperti, CSS personalizzato applicato solo all'interno della finestra della chat (licenze a pagamento).

Comportamento

Richieste di contatto

Veda il capitolo "Richieste di contatto".

Dove e quando

Mostrare la chat su ogni pagina, solo sulle pagine che corrispondono a determinati pattern oppure ovunque tranne queste (i pattern usano *); su tutti i dispositivi, solo desktop o solo mobile; solo negli orari di apertura, con un messaggio o senza nulla al di fuori di essi. Licenze a pagamento.

Testi

Per lingua: titolo della finestra, saluto, segnaposto del campo di input, domande suggerite (fino a cinque pulsanti), avviso IA, messaggi di errore e offline, etichetta del pulsante di invio, e introduzione e ringraziamento del modulo di contatto. I campi vuoti usano le traduzioni integrate, quindi il widget parla la lingua del visitatore anche se non si scrive nulla.

Sicurezza

Privacy

Branding

La piccola riga "Powered by" in fondo alla chat. Con la licenza Free è sempre attiva; Single e Agency possono nasconderla; Agency può sostituirne testo e link (white label).

Incorporamento e Chat di prova

La scheda Incorporamento contiene lo script, il plugin WordPress e una pagina di prova già pronta. Chat di prova dialoga con il bot all'interno del pannello senza salvare nulla.

Inserire la chat nel Suo sito web

Una riga di codice, oppure un piccolo plugin. Il widget si disegna all'interno di uno Shadow DOM, quindi gli stili del Suo sito non possono comprometterlo ed esso non può compromettere il Suo sito.

Qualsiasi sito web

Apra il Suo bot, la scheda Incorporamento, copi lo script e lo incolli subito prima del tag di chiusura </body> in ogni pagina in cui deve comparire la chat:

<script src="https://your-site/ai-chat-widget/assets/widget/loader.js"
        data-bot="YOUR-BOT-ID" async></script>

Poi aggiunga il Suo sito web in Sicurezza > Siti consentiti, altrimenti la chat non si caricherà.

WordPress

La scheda Incorporamento offre un piccolo plugin (un file .zip, oppure un singolo file .php se il server non ha l'estensione zip). Lo carichi da Plugin > Aggiungi nuovo > Carica plugin, lo attivi e la chat comparirà su ogni pagina. Il plugin aggiunge soltanto la riga di script con l'ID del Suo bot; la chat, le chiavi IA e le conversazioni restano sulla Sua installazione.

Attributi facoltativi dello script

Controllare la chat dalla Sua pagina

AIChatWidget.open();    // open the window
AIChatWidget.close();   // close it
AIChatWidget.toggle();  // open or close
AIChatWidget.setContext({ title: 'Red city bike', url: location.href });

Li usi per aprire la chat da un Suo pulsante o per indicare al bot quale prodotto sta guardando il visitatore.

Che cosa vedono i visitatori

Un pulsante rotondo nell'angolo; una finestra con un'intestazione (titolo, pulsante di contatto se attivato, riavvio, chiusura), la conversazione con formattazione Markdown, pulsanti con domande suggerite, pollici, link alle fonti, l'avviso IA e un campo di input. Sugli smartphone la finestra occupa l'intero schermo. La conversazione resiste ai ricaricamenti della pagina durante la sessione del browser.

Base di conoscenza

La base di conoscenza contiene i fatti da cui i Suoi bot traggono le risposte: prezzi, condizioni, FAQ, dettagli sui prodotti. Quando un visitatore pone una domanda, il bot cerca gli estratti più pertinenti e risponde in base a questi anziché tirare a indovinare.

Modi per aggiungere contenuti

Quale bot usa un documento

Ogni documento appartiene a un bot oppure a tutti i bot. Usi "tutti i bot" per le informazioni valide per l'intera azienda, come spedizioni e resi. Un documento può essere disattivato senza eliminarlo. Le pagine importate possono essere rilette con un clic per aggiornarle.

Come lo usa un bot

Nella scheda Argomento e prompt del bot scelga la modalità:

• Usarla e ricorrere alla conoscenza generale (predefinita). Gli estratti pertinenti vengono aggiunti alle istruzioni. Il bot può comunque ricorrere alla conoscenza generale dove gli estratti non dicono nulla.
• Rispondere solo dalla base di conoscenza. Quando nulla corrisponde, l'IA non viene interpellata affatto: il bot risponde con il testo "quando non sa rispondere", che non costa token, evita risposte inventate e contrassegna la domanda come senza risposta.
• Non usarla.

Una richiesta di approfondimento molto breve, come "e la garanzia?", viene cercata insieme alla domanda precedente. I documenti provenienti da un indirizzo web aggiungono un link alla fonte sotto la risposta.

Ricerca

La ricerca non richiede alcun servizio esterno. Il testo viene suddiviso in estratti; le parole vengono ridotte alla radice (accenti e desinenze non contano), l'indice full-text del database sceglie i candidati e una classifica di pertinenza (BM25) individua i migliori. Funziona in tutte e sei le lingue del pannello. Una domanda in una lingua diversa da quella del documento non troverà corrispondenze: scriva i documenti nella lingua usata dai visitatori.

Provare una ricerca

Il riquadro Provi una ricerca nella pagina Base di conoscenza mostra quali estratti riceverebbe un bot per una domanda, con un punteggio di pertinenza. Lo usi dopo aver aggiunto dei documenti.

Chiudere il cerchio

In Statistiche, ogni domanda senza risposta ha un link Aggiungi una risposta alla base di conoscenza. Apre un modulo di domanda e risposta con la domanda e il bot già compilati. Scriva la risposta e salvi: la volta successiva il bot la conoscerà.

Limiti

Richieste di contatto

Quando il bot non può aiutare, il visitatore può lasciare i propri dati invece di abbandonare il sito. Lei riceve un'e-mail per ogni richiesta e un elenco nel pannello.

Attivazione

1. 1
   Configuri la posta in uscita in Impostazioni > E-mail e invii il messaggio di prova.
2. 2
   Apra il bot, scheda Richieste di contatto, e spunti Raccogli richieste di contatto.
3. 3
   Scelga quando proporre il modulo: un pulsante nell'intestazione della chat e/o subito dopo una risposta che il bot non ha saputo dare.
4. 4
   Scelga quali campi mostrare (nome, telefono, messaggio: nascosto, facoltativo od obbligatorio; l'indirizzo e-mail è sempre obbligatorio), se chiedere il consenso e chi viene avvisato.

Gestire le richieste

La pagina Richieste di contatto elenca tutte le richieste con filtri (ricerca, bot, stato). Ne apra una per vedere il messaggio, la pagina in cui si trovava il visitatore e la conversazione da cui proviene. Può segnare le richieste come gestite, eliminarle una per una o in blocco ed esportarle in CSV (licenze a pagamento). I filtri attivi sono evidenziati e conteggiati accanto a "Reimposta filtri".

Protezione

Il modulo funziona anche fuori dagli orari di apertura. Dispone di un campo trappola nascosto per i bot, di un limite di sei richieste per visitatore e tre per indirizzo e-mail all'ora, e controlla ogni campo sul server.

Conversazioni

Legga che cosa hanno chiesto i visitatori, contrassegni ciò che conta e mantenga ordinato il database senza alcuna attività pianificata.

L'elenco

Si può filtrare per bot, intervallo di date, testo di ricerca e vista: tutte, fissate, senza risposta, valutate non utili o con errori. Ogni riga mostra dei segnali: pollici, "senza risposta" ed errori del provider. Aprendone una, si legge l'intero scambio con token, tempo di risposta e contrassegni.

Azioni

Fissi le conversazioni che desidera conservare, ne elimini una o più, oppure elimini tutte quelle di un bot. Esporta (CSV o JSON, licenze a pagamento) mantiene i Suoi filtri; le celle CSV che potrebbero essere eseguite come formule di un foglio di calcolo vengono neutralizzate.

Modalità di registrazione

Ciò che viene salvato dipende dall'impostazione Registro conversazioni di ciascun bot: testi completi, solo metadati (conteggi, tempi, valutazioni) oppure nulla. Con "metadati" o "disattivato" è il browser del visitatore a conservare la cronologia per la durata della sessione.

Pulizia automatica

Le vecchie conversazioni vengono rimosse secondo regole: per età, per numero e per dimensione, per ciascun bot (regole proprie o valori predefiniti) e per l'intero database (numero totale e dimensione totale). Le conversazioni fissate non vengono mai rimosse automaticamente. Non c'è alcun cron: la pulizia si avvia da sola quando l'applicazione viene usata, al massimo una volta al minuto. Pulisci ora mostra prima un'anteprima (quante conversazioni, quanti kilobyte e per quale motivo) e chiede conferma.

Statistiche

I contatori sono conservati come totali giornalieri anonimi, quindi le statistiche funzionano anche per i bot che non salvano conversazioni.

I riquadri mostrano risposte, token, errori, domande senza risposta, messaggi bloccati e valutazioni. Tre grafici mostrano risposte, token e problemi per giorno. Una tabella confronta i Suoi bot. Con una licenza a pagamento due elenchi mostrano le ultime domande senza risposta (ognuna con un link per aggiungere una risposta alla base di conoscenza) e le risposte valutate non utili: il modo più rapido per migliorare un bot.

Impostazioni

Opzioni valide per l'intera applicazione, suddivise in schede.

Streaming delle risposte

Con lo streaming attivo, i visitatori vedono la risposta comparire parola per parola. Occorre un server che non trattenga le risposte, quindi prema prima Testa lo streaming: invia sei porzioni a mezzo secondo di distanza e indica se arrivano una alla volta. Se il test segnala che è arrivato tutto in una volta, lasci lo streaming disattivato. I provider che non supportano lo streaming consegnano semplicemente l'intera risposta in una volta.

E-mail e notifiche

La posta in uscita serve per la reimpostazione della password, i codici di accesso e le notifiche sulle nuove richieste di contatto. È facoltativa; tutto il resto funziona anche senza.

Configurazione

Prema Salva e invia e-mail di prova. Se il messaggio arriva, tutto funziona.

Testi delle e-mail

In Impostazioni > Testi e-mail scelga un'e-mail (reimpostazione della password, password modificata, codice di accesso, nuova richiesta di contatto, conferma al visitatore, prova) e una lingua, poi modifichi l'oggetto e il testo. I {segnaposto} come {name}, {link} o {code} vengono sostituiti al momento dell'invio. Ripristina il testo integrato riporta al testo predefinito. Le e-mail destinate alle persone sono scritte nella lingua scelta nel loro profilo.

Account, autenticazione a due fattori e registro di controllo

Ogni utente è un amministratore; non ci sono ruoli da configurare. L'accesso è protetto da password, autenticazione a due fattori facoltativa e un registro di controllo completo.

Utenti

In Utenti si aggiungono o si rimuovono gli amministratori (il numero dipende dalla Sua licenza), si reimposta l'autenticazione a due fattori di un collega che ha perso il dispositivo e si vede chi ha effettuato l'accesso e quando.

Autenticazione a due fattori

Apra Il mio profilo > Autenticazione a due fattori e scelga una delle opzioni:

• App di autenticazione. Scansioni o digiti la chiave in un'app come Google Authenticator, Microsoft Authenticator o Aegis, poi inserisca il codice di 6 cifre per confermare.
• Codice via e-mail. A ogni accesso viene inviato via e-mail un codice di 6 cifre (valido dieci minuti, cinque tentativi). Richiede una posta in uscita funzionante. Conferma inserendo un codice inviato al Suo indirizzo.

In entrambi i casi riceve una sola volta i codici di ripristino. Li conservi con cura: ciascuno funziona una sola volta se non può usare il normale secondo passaggio. Impostazioni > Generale > Richiedi l'autenticazione a due fattori la rende obbligatoria per tutti.

Password dimenticata

Quando la posta in uscita è configurata, la pagina di accesso mostra Ha dimenticato la password?. Viene inviato via e-mail un link monouso valido 60 minuti; la risposta mostrata è la stessa sia che l'indirizzo esista sia che non esista. Impostare una nuova password rimuove il blocco dell'account e invia un avviso. Senza e-mail, un altro amministratore imposta per Lei una nuova password in Utenti.

Blocchi e limiti

Cinque password errate bloccano un account per 15 minuti; troppi errori da un unico indirizzo vengono rallentati. Le sessioni scadono dopo il tempo impostato in Impostazioni.

Registro di controllo

Ogni azione importante viene registrata: accessi ed errori di accesso, modifiche alle impostazioni, modifiche a chiavi e licenza, modifiche agli utenti, esportazioni, eliminazioni. Il registro non salva mai password, chiavi né testi dei messaggi. Le voci più vecchie vengono rimosse dopo il numero di giorni impostato in Impostazioni.

Info di sistema, aggiornamenti e dati demo

Dettagli tecnici e strumenti a un clic.

Info di sistema mostra le versioni dell'applicazione e di PHP, il database, quali estensioni PHP sono caricate, i permessi dei file e l'elenco degli aggiornamenti del database (migrazioni). Quando una nuova versione porta modifiche al database, la dashboard mostra un avviso; apra Info di sistema e prema Applica aggiornamenti. Gli aggiornamenti sono numerati, vengono eseguiti una sola volta e si possono ripetere senza rischi.

Dati demo

Impostazioni > Dati demo carica quattro bot di esempio (negozio di biciclette, FAQ di uno studio legale, assistente di vendita SaaS, selezione del personale) con circa cento conversazioni distribuite su sei mesi, alcune fissate e valutate, domande senza risposta, richieste di contatto e documenti della base di conoscenza. La pulizia automatica viene sospesa mentre i dati sono caricati (altrimenti le conversazioni volutamente vecchie sparirebbero). Rimuovi dati demo elimina esattamente i bot demo e i loro dati e ripristina la Sua precedente impostazione di pulizia.

Licenze

L'applicazione è gratuita per uso personale. Le licenze a pagamento sono destinate all'uso commerciale ed eliminano i limiti.

Attivare una chiave

Vada in Impostazioni > Licenza, incolli la chiave e salvi. La chiave viene verificata sul Suo server rispetto a una chiave pubblica integrata ed è legata al Suo dominio: nessun dato viene inviato altrove. Se la chiave non corrisponde al dominio o è scaduta, l'applicazione resta in modalità Free; i widget attivi non vengono mai disattivati, viene solo limitata la creazione di nuovi elementi.

Per gli sviluppatori: l'API del widget

Il widget comunica con api.php sul Suo server. Non ci sono cookie né sessioni: un visitatore è un token casuale conservato nel browser.

Ogni richiesta deve provenire da un sito consentito (l'intestazione Origin viene confrontata con l'elenco del bot). Le risposte sono in JSON con ok e, in caso di errore, un codice error e un message tradotto. Le risposte in streaming usano gli eventi delta (un frammento di testo), done (risposta finale, conversazione, firma, fonti) ed error.

Note su privacy e GDPR

Decide Lei che cosa viene salvato. Queste impostazioni La aiutano a rispettare i Suoi obblighi; non costituiscono consulenza legale.

• Modalità di registrazione per bot. Completa, solo metadati o disattivata. Scelga ciò che serve davvero.
• Indirizzi IP. Salvati abbreviati (senza l'ultima parte) oppure non salvati affatto.
• Conservazione. Elimini le conversazioni per età, numero o dimensione, e le richieste di contatto dopo un certo numero di giorni. Entrambe le operazioni sono automatiche.
• Eliminazione su richiesta. Elimini le conversazioni di una persona dall'elenco (cercando nel testo) e la sua richiesta di contatto da Richieste di contatto.
• Avviso sull'IA. Una breve frase nella chat che informa il visitatore che sta parlando con un'IA; rimanda alla Sua informativa sulla privacy.
• Consenso. Una casella obbligatoria nel modulo di contatto.
• Dati in transito. I messaggi vengono inviati al provider IA che ha scelto. Verifichi le sue condizioni e l'accordo sul trattamento dei dati, e lo citi nella Sua informativa sulla privacy. Scelga un provider o un modello adatto ai Suoi obblighi, oppure un modello locale (Ollama, LM Studio) se i dati non devono lasciare il Suo server.
• I Suoi dati restano presso di Lei. L'applicazione in sé non invia nulla a CreativAI.

Panoramica della sicurezza

Difesa a più livelli, senza servizi aggiuntivi.

• Accesso. Password con hash, blocco dopo errori ripetuti, autenticazione a due fattori facoltativa con codici di ripristino, sessioni che scadono.
• Moduli. Protezione CSRF su ogni modifica; tutto l'output è sottoposto a escape; criterio di sicurezza dei contenuti con nonce.
• Segreti. Le chiavi IA, la password SMTP e i segreti dell'autenticazione a due fattori sono cifrati con AES-256-GCM tramite la chiave della Sua applicazione.
• Identificatori pubblici. Bot, conversazioni e richieste di contatto usano UUID casuali negli indirizzi, mai numeri progressivi.
• Widget. Costruito solo con chiamate DOM (nessun HTML grezzo dal modello), all'interno di uno Shadow DOM; i link nelle risposte si aprono con rel="noopener noreferrer nofollow".
• Limiti contro gli abusi. Elenco dei siti consentiti, limite di frequenza, limiti di lunghezza di messaggi e conversazioni, parole bloccate, budget giornaliero di token, un campo trappola nascosto e limiti per indirizzo sul modulo di contatto.
• Richieste in uscita. Le chiamate IA e le importazioni di pagine web vengono verificate rispetto agli indirizzi privati e ai metadati cloud, i reindirizzamenti sono controllati a ogni passaggio, dimensione e durata sono limitate.
• Prompt injection. Il testo del visitatore, il contesto della pagina e gli estratti di conoscenza sono etichettati come dati non attendibili e vengono sempre aggiunte regole di sicurezza fisse. Un prompt riduce questo rischio ma non lo elimina: mantenga ristretto l'ambito del bot e non inserisca mai segreti nelle istruzioni o nella base di conoscenza di un bot.
• File. I caricamenti vengono controllati per tipo e dimensione e letti come testo; i documenti Word vengono analizzati con le entità esterne disabilitate.

Manutenzione

Una breve routine per mantenere l'installazione in buona salute.

Backup

Esegua il backup di due elementi: il database e il file **config/config.php** (contiene la chiave che decifra le Sue chiavi IA salvate). I documenti caricati sono salvati nel database, quindi un dump del database comprende anche la base di conoscenza.

Aggiornamento

1. 1
   Esegua un backup del database.
2. 2
   Carichi i nuovi file sopra quelli vecchi; mantenga config/ e storage/.
3. 3
   Acceda, apra Info di sistema e prema Applica aggiornamenti se ne sono elencati.
4. 4
   Prema una volta Ctrl+F5 per aggiornare il foglio di stile.

Log

Gli errori che non possono essere mostrati ai visitatori vengono scritti nel log degli errori di PHP. Il registro di controllo nel pannello registra le azioni amministrative.

Regole per Nginx

I file .htaccess proteggono le cartelle interne su Apache. Su Nginx aggiunga regole equivalenti, ad esempio:

location ~ ^/ai-chat-widget/(app|config|database|language|storage|_devs|_idea)/ { deny all; }
location ~* \.(sql|md|lock|log|json)$ { deny all; }

Per lo streaming dietro Nginx, si assicuri che proxy_buffering sia disattivato per api.php (l'applicazione invia già X-Accel-Buffering: no).

Limiti dell'hosting che contano

In PHP, upload_max_filesize e post_max_size limitano i caricamenti di file nella base di conoscenza. Un PDF di grandi dimensioni può richiedere un memory_limit di 256 MB o più. L'HTTPS in uscita deve essere consentito per le chiamate IA e le importazioni di pagine web.

Problemi comuni e soluzioni

Parta dal sintomo.

Interpretare gli errori del provider

Domande frequenti

Ho bisogno di uno sviluppatore per usarla?

No. Tutto si configura nel pannello e ogni campo ha un'icona di guida. Uno sviluppatore serve solo per integrazioni insolite.

Dove sono conservate le mie chiavi IA?

Cifrate nel Suo database. Non vengono mai inviate al browser del visitatore né scritte nei log.

Quanto mi costerà l'IA?

Il provider Le addebita direttamente i token. Usi il budget giornaliero di token, una lunghezza di risposta ridotta e la modalità "Rispondi solo dalla base di conoscenza" per mantenere i costi prevedibili, e tenga d'occhio i token nella pagina Statistiche.

Posso usare un modello che gira sul mio computer o server?

Sì. Usi il profilo Ollama o LM Studio e attivi per esso "Consenti indirizzi di rete privata".

Una sola installazione può servire più siti web?

Sì. Aggiunga ogni sito all'elenco consentito del bot, oppure crei un bot per sito. Il numero di bot e di siti dipende dalla Sua licenza.

Che cosa succede se la mia licenza scade?

L'applicazione torna ai limiti Free. I widget esistenti continuano a funzionare; viene bloccata solo la creazione di nuovi bot, siti e documenti oltre i limiti Free.

Posso cambiare i testi del widget?

Sì: nella scheda Testi, per lingua. I campi vuoti usano le traduzioni integrate.

Funziona con i page builder e i negozi online?

Sì. È una singola riga di script, quindi funziona ovunque sia possibile modificare il piè di pagina o aggiungere uno script. È incluso un plugin per WordPress.