Helvira AI ChatBot - WordPress
Chatbot alimentato dall'IA con capacità RAG per WordPress
Introduzione
Helvira AI ChatBot è un potente plugin WordPress che aggiunge un chatbot intelligente alimentato dall'IA al tuo sito web. Il chatbot utilizza la tecnologia RAG (Retrieval-Augmented Generation) per rispondere alle domande sui contenuti del tuo sito, prodotti e servizi.
Funzionalità principali
- 🤖 Risposte alimentate dall'IA - Utilizza modelli linguistici avanzati per conversazioni naturali
- 📚 Tecnologia RAG - Indicizza automaticamente i tuoi contenuti per risposte accurate
- 🛒 Integrazione WooCommerce - Assistente allo shopping con gestione del carrello
- 🌍 Supporto multilingue - Rileva automaticamente e risponde nella lingua dell'utente
- 🎨 Design personalizzabile - Adatta al tuo brand con colori, gradienti e loghi personalizzati
- 📱 Responsive mobile - Funziona perfettamente su tutti i dispositivi
- 💬 Cronologia conversazioni - Mantiene il contesto durante tutta la sessione di chat
Requisiti
| Requisito | Minimo | Raccomandato |
|---|---|---|
| WordPress | 5.8+ | 6.0+ |
| PHP | 7.4+ | 8.0+ |
| MySQL | 5.7+ | 8.0+ |
| WooCommerce | 6.0+ (opzionale) | 8.0+ |
Requisiti server
- Estensione PHP
cURLabilitata - Estensione PHP
JSONabilitata - Connessioni HTTPS in uscita consentite (per chiamate API)
Installazione
Metodo 1: Upload tramite admin WordPress
- Scarica il file ZIP del plugin
- Vai su Admin WordPress → Plugin → Aggiungi nuovo
- Clicca su Carica plugin
- Seleziona il file ZIP e clicca su Installa ora
- Clicca su Attiva plugin
Metodo 2: Installazione manuale (FTP)
- Estrai il file ZIP del plugin
- Carica la cartella
helvirain/wp-content/plugins/ - Vai su Admin WordPress → Plugin
- Trova "Helvira AI Chat" e clicca su Attiva
Configurazione
Dopo l'attivazione, vai su Admin WordPress → Helvira Chat per configurare il plugin.
Impostazioni generali
Abilita chatbot
Attiva questa opzione per mostrare o nascondere il chatbot sul tuo sito.
- Abilitato: Il chatbot è visibile a tutti i visitatori
- Disabilitato: Il chatbot è nascosto (utile per manutenzione)
Titolo chat
Il titolo visualizzato nell'intestazione del widget chat.
Esempio: "Chatta con noi", "Hai bisogno di aiuto?", "Chiedimi qualsiasi cosa"
Messaggio di benvenuto
Il primo messaggio visualizzato quando un visitatore apre la chat.
Best practice:
- Mantienilo amichevole e conciso
- Menziona in cosa il chatbot può aiutare
- Considera il tono del tuo brand
Esempio:
Ciao! 👋 Sono qui per aiutarti a scoprire i nostri prodotti e servizi. Cosa vorresti sapere?
Configurazione API
Chiave API
La tua chiave API Helvira è necessaria per il funzionamento del chatbot.
Come ottenere una chiave API:
- Vai su chat.helvira.ai
- Crea un account o accedi
- Naviga su Impostazioni → Account → Chiavi API → Mostra
- Copia la chiave e incollala nelle impostazioni del plugin
⚠️ Nota sulla sicurezza: Non condividere mai la tua chiave API pubblicamente. Il plugin la memorizza in modo sicuro nel tuo database WordPress.
Modello IA
Scegli il tuo modello in base al tuo abbonamento:
| Nome modello |
|---|
| Gemmini Light (Gemma3) Standard |
| Gemmini (Gemma3) Premium |
| OSS (gpt-oss) Premium |
Impostazioni aspetto
Stile colore
Scegli tra due modalità di colore:
Colore solido
- Un solo colore per tutti gli elementi
- Look pulito e professionale
- Ideale per design minimalisti
Gradiente
- Effetto gradiente a due colori
- Aspetto moderno e dinamico
- Direzione personalizzabile
Colore primario
Il colore principale utilizzato per:
- Pulsante chat
- Sfondo intestazione
- Pulsante invio
- Bolle messaggi utente
Predefinito: #667eea (Blu-viola)
Colore secondario (solo gradiente)
Il secondo colore per gli effetti gradiente.
Predefinito: #764ba2 (Viola)
Direzione gradiente
Scegli come fluisce il gradiente:
| Opzione | Direzione |
|---|---|
| ↘️ Diagonale | Alto-sinistra verso basso-destra (135deg) |
| → Orizzontale | Sinistra verso destra |
| ↓ Verticale | Alto verso basso |
| ↗️ Diagonale ascendente | Basso-sinistra verso alto-destra (45deg) |
Posizione widget
Dove appare il pulsante chat sul tuo sito:
- Basso destra (raccomandato) - Posizione standard, non interferisce con il contenuto
- Basso sinistra - Posizione alternativa per siti RTL o per preferenza
- Alto sinistra
- Alto destra
Logo personalizzato
Carica un'immagine personalizzata per il pulsante chat.
Specifiche:
- Formato: PNG (con trasparenza) o JPG
- Dimensione: 40x40 pixel raccomandato
- Peso file: Sotto 100KB per migliori prestazioni
Per caricare:
- Clicca su Carica
- Seleziona o carica un'immagine
- Clicca su Usa questa immagine
Indicizzazione contenuti
Il sistema RAG indicizza i contenuti del tuo sito così l'IA può rispondere alle domande con precisione.
Tipi di post da indicizzare
Seleziona quali tipi di contenuto devono essere ricercabili:
- ✅ Articoli - Post del blog, articoli
- ✅ Pagine - Pagine statiche, chi siamo, contatti
- ✅ Prodotti - Prodotti WooCommerce (se installato)
Raccomandazione: Abilita tutti i tipi di contenuto pubblici per una copertura completa.
Chunk di contesto massimi
Quanti chunk di contenuto includere nel contesto IA (1-20).
| Impostazione | Compromesso |
|---|---|
| 1-3 | Più veloce, meno contesto |
| 4-6 | Bilanciato (raccomandato) |
| 7-10 | Più contesto, più lento |
| 11-20 | Contesto massimo, più lento |
Predefinito: 5 chunk
Dimensione chunk (parole)
Numero di parole per chunk di contenuto (100-2000).
- Chunk più piccoli (100-300): Corrispondenza più precisa, meno contesto per chunk
- Chunk più grandi (500-1000): Più contesto, potenzialmente meno preciso
- Predefinito: 500 parole
Sovrapposizione chunk (parole)
Sovrapposizione tra chunk consecutivi per continuità (0-500).
- Perché la sovrapposizione? Assicura che le informazioni importanti ai confini dei chunk non vengano perse
- Predefinito: 100 parole
Reindicizzazione contenuti
Clicca su Reindicizza tutti i contenuti per ricostruire l'indice dei contenuti. Fallo dopo:
- Aggiunta o aggiornamento di contenuti significativi
- Modifica dei tipi di post indicizzati
- Modifica delle impostazioni dimensione/sovrapposizione chunk
- Configurazione iniziale del plugin
ℹ️ La reindicizzazione può richiedere diversi minuti per siti di grandi dimensioni.
Integrazione WooCommerce
Se WooCommerce è installato, diventano disponibili funzionalità aggiuntive.
Abilita assistente allo shopping
Quando abilitato, il chatbot può:
- 🛒 Visualizzare contenuto carrello - Vedere quali articoli sono nel carrello del cliente
- ➕ Aggiungere prodotti - Aggiungere articoli al carrello via chat
- ➖ Rimuovere prodotti - Rimuovere articoli dal carrello
- 🎫 Applicare coupon - Applicare codici sconto
- 📦 Informazioni prodotto - Fornire dettagli sui prodotti
- 💡 Raccomandazioni - Suggerire prodotti rilevanti
Esempi di conversazione
Aggiunta al carrello:
Utente: Aggiungi questo prodotto al mio carrello
Bot: ✓ "Nome prodotto" aggiunto al tuo carrello. Il tuo carrello ora contiene 2 articoli.
Applicazione coupon:
Utente: Ho un codice sconto RISPARMIA20
Bot: ✓ Coupon "RISPARMIA20" applicato! Stai risparmiando il 20% sul tuo ordine.
Domande sui prodotti:
Utente: È disponibile?
Bot: Sì! Il "Nome prodotto" è attualmente disponibile con 15 unità.
Il prezzo è 49,99€. Vuoi che lo aggiunga al tuo carrello?
Funzionalità
Supporto multilingue
Il chatbot rileva automaticamente e risponde nella lingua dell'utente.
Lingue supportate per il carrello:
- 🇬🇧 English
- 🇫🇷 Français
- 🇩🇪 Deutsch
- 🇪🇸 Español
- 🇮🇹 Italiano
Come funziona:
- L'utente invia un messaggio nella sua lingua
- L'IA rileva la lingua
- La risposta viene generata nella stessa lingua
Consapevolezza del contesto della pagina
Il chatbot sa quale pagina il visitatore sta attualmente visualizzando.
Esempio:
Utente: Puoi riassumere questa pagina?
Bot: Stai visualizzando la nostra pagina "Chi siamo". Questa pagina spiega
la storia della nostra azienda, fondata nel 2010, la nostra missione
di fornire prodotti di qualità, e presenta il nostro team di oltre 50 dipendenti...
Cronologia conversazioni
- La cronologia chat viene conservata durante la sessione
- L'IA ricorda il contesto dei messaggi precedenti
- Gli utenti possono cancellare la cronologia con il pulsante 🗑️
Citazione delle fonti
Quando risponde dai contenuti indicizzati, il chatbot può mostrare le fonti:
Bot: La nostra politica di reso consente resi entro 30 giorni dall'acquisto...
Fonti:
• Politica di reso
• FAQ - Spedizione & Resi
Come funziona
RAG (Retrieval-Augmented Generation)
┌─────────────────────────────────────────────────────────────┐
│ Messaggio utente │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Rilevamento intento │
│ Determinare se è domanda chat o azione carrello │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ Domanda chat │ │ Azione carrello │
└─────────────────────────┘ └─────────────────────────┘
│ │
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ 2. Cerca contenuti │ │ 2. Esegui azione │
│ indicizzati (RAG) │ │ (Aggiungi/Rimuovi) │
└─────────────────────────┘ └─────────────────────────┘
│ │
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ 3. Costruisci contesto │ │ 3. Conferma azione │
│ + Info pagina │ │ + Aggiorna carrello │
└─────────────────────────┘ └─────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Risposta IA │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Mostra all'utente │
└─────────────────────────────────────────────────────────────┘
Processo di indicizzazione contenuti
- Estrazione: Il contenuto viene estratto da articoli, pagine e prodotti
- Chunking: Il contenuto viene diviso in chunk gestibili
- Memorizzazione: I chunk vengono memorizzati nel database con metadati
- Recupero: I chunk rilevanti vengono recuperati in base alle query utente
Risoluzione problemi
Il chatbot non appare
Possibili cause e soluzioni:
| Causa | Soluzione |
|---|---|
| Plugin disabilitato | Abilitare in Helvira Chat → Impostazioni generali |
| Errore JavaScript | Controllare la console del browser per errori |
| Conflitto tema | Testare con tema predefinito |
| Cache | Svuotare cache del sito e del browser |
Errore "Chiave API non valida"
- Verifica che la chiave API sia corretta (nessuno spazio extra)
- Controlla se la chiave è scaduta
- Assicurati che il tuo account API sia attivo
- Testa la connessione nelle impostazioni
Il chatbot dà risposte sbagliate
- Reindicizza i contenuti - Clicca su "Reindicizza tutti i contenuti"
- Controlla i tipi di post indicizzati - Assicurati che i contenuti rilevanti siano indicizzati
- Aumenta i chunk massimi - Permetti più contesto per risposte migliori
- Rivedi la qualità dei contenuti - L'IA può usare solo ciò che è indicizzato
Risposte lente
| Causa | Soluzione |
|---|---|
| Dimensione chunk grande | Ridurre la dimensione chunk a 300-500 |
| Troppi chunk | Ridurre i chunk massimi a 3-5 |
| API lenta | Controllare lo stato API, provare modello diverso |
| Problemi server | Controllare risorse server |
Azioni carrello WooCommerce non funzionano
- Assicurati che Abilita assistente allo shopping sia ON
- Controlla che WooCommerce sia attivo e aggiornato
- Verifica che il prodotto esista e sia disponibile
- Svuota i transient WooCommerce
La cronologia chat non si salva
- La cronologia è memorizzata nel sessionStorage del browser
- Si cancella alla chiusura della scheda (per design)
- La modalità privata/incognito può bloccare la memorizzazione
FAQ
Domande generali
D: Il chatbot è gratuito? R: Il plugin è gratuito, ma richiede una chiave API da Helvira AI che può avere costi associati in base all'utilizzo.
D: Funziona con qualsiasi tema? R: Sì, Helvira Chat è progettato per funzionare con qualsiasi tema WordPress correttamente codificato.
D: Posso usarlo su più siti? R: Controlla i termini di licenza della tua chiave API. Alcuni piani permettono più siti.
D: I miei dati sono sicuri? R: Sì. Le conversazioni sono elaborate tramite connessioni HTTPS sicure. Non memorizziamo i dati delle conversazioni sui nostri server.
Domande tecniche
D: Influisce sulla velocità del sito? R: Il widget chat si carica in modo asincrono e ha un impatto minimo sul tempo di caricamento (~50KB).
D: Posso personalizzare la personalità dell'IA? R: L'IA si adatta al nome e alla descrizione del tuo sito. Prompt di sistema personalizzati potrebbero essere disponibili in versioni future.
D: Funziona con i page builder? R: Sì, compatibile con Elementor, Divi, Beaver Builder e altri.
D: Posso escludere determinate pagine? R: Non attualmente. Questa funzionalità è pianificata per una versione futura.
Domande WooCommerce
D: Il chatbot può processare pagamenti? R: No, può guidare gli utenti al checkout ma non gestisce l'elaborazione dei pagamenti.
D: Supporta prodotti variabili? R: Sì, può aggiungere prodotti variabili con le variazioni selezionate.
D: Può accedere alla cronologia ordini? R: Attualmente limitato. Le funzionalità complete di cronologia ordini sono pianificate.
Changelog
Versione 1.0.0 (Release iniziale)
- ✅ Chatbot alimentato dall'IA con RAG
- ✅ Indicizzazione contenuti per articoli, pagine, prodotti
- ✅ Integrazione WooCommerce (azioni carrello)
- ✅ Supporto multilingue
- ✅ Aspetto personalizzabile (colori, gradienti, logo)
- ✅ Design responsive mobile
- ✅ Cronologia conversazioni
- ✅ Consapevolezza contesto pagina
- ✅ UI impostazioni admin moderna
Supporto
Documentazione: docs.helvira.ai
Email supporto: support@helvira.ai
Issues GitHub: github.com/helvira/chat-plugin/issues
Licenza
Questo plugin è sotto licenza GPL v2 o successiva.
Questo programma è software libero; puoi ridistribuirlo e/o modificarlo
secondo i termini della GNU General Public License come pubblicata dalla
Free Software Foundation; sia la versione 2 della Licenza, sia
(a tua scelta) qualsiasi versione successiva.
Fatto con ❤️ da Helvira AI