Helvira AI ChatBot - WordPress

AI-powered chatbot with RAG capabilities for WordPress

Introduction

Helvira AI ChatBot is a powerful WordPress plugin that adds an intelligent AI chatbot to your website. The chatbot uses RAG (Retrieval-Augmented Generation) technology to answer questions about your website content, products, and services.

Key Features

• 🤖 AI-Powered Responses - Uses advanced language models for natural conversations
• 📚 RAG Technology - Automatically indexes your content for accurate answers
• 🛒 WooCommerce Integration - Shopping assistant with cart management
• 🌍 Multi-Language Support - Automatically detects and responds in user's language
• 🎨 Customizable Design - Match your brand with colors, gradients, and custom logos
• 📱 Mobile Responsive - Works perfectly on all devices
• 💬 Conversation History - Maintains context throughout the chat session

---

Requirements

Requirement	Minimum	Recommended
WordPress	5.8+	6.0+
PHP	7.4+	8.0+
MySQL	5.7+	8.0+
WooCommerce	6.0+ (optional)	8.0+

Server Requirements

• cURL PHP extension enabled
• JSON PHP extension enabled
• Outbound HTTPS connections allowed (for API calls)

---

Installation

Method 1: Upload via WordPress Admin

1. Download the plugin ZIP file
2. Go to WordPress Admin → Plugins → Add New
3. Click Upload Plugin
4. Select the ZIP file and click Install Now
5. Click Activate Plugin

Method 2: Manual Installation (FTP)

1. Extract the plugin ZIP file
2. Upload the helvira folder to /wp-content/plugins/
3. Go to WordPress Admin → Plugins
4. Find "Helvira AI Chat" and click Activate

---

Configuration

After activation, go to WordPress Admin → Helvira Chat to configure the plugin.

General Settings

Enable Chatbot

Toggle this option to show or hide the chatbot on your website.

• Enabled: Chatbot is visible to all visitors
• Disabled: Chatbot is hidden (useful for maintenance)

Chat Title

The title displayed in the chat widget header.

Example: "Chat with us", "Need help?", "Ask me anything"

Welcome Message

The first message displayed when a visitor opens the chat.

Best Practices:

• Keep it friendly and concise
• Mention what the chatbot can help with
• Consider your brand voice

Example:

Hello! 👋 I'm here to help you learn about our products and services. What would you like to know?

---

API Configuration

API Key

Your Helvira API key is required for the chatbot to function.

How to get an API key:

1. Go to chat.helvira.ai
2. Create an account or log in
3. Navigate to Settings → Account → API Keys → Show
4. Copy the key and paste it in the plugin settings

⚠️ Security Note: Never share your API key publicly. The plugin stores it securely in your WordPress database.

AI Model

Choose your model based on your subscription:

Model Name
Gemmini Light (Gemma3) Standard
Gemmini (Gemma3) Premium
OSS (gpt-oss) Premium

---

Appearance Settings

Color Style

Choose between two color modes:

Solid Color

• Single color for all elements
• Clean, professional look
• Best for minimalist designs

Gradient

• Two-color gradient effect
• Modern, dynamic appearance
• Customizable direction

Primary Color

The main color used for:

• Chat button
• Header background
• Send button
• User message bubbles

Default: #667eea (Purple-blue)

Secondary Color (Gradient only)

The second color for gradient effects.

Default: #764ba2 (Purple)

Gradient Direction

Choose how the gradient flows:

Option	Direction
↘️ Diagonal	Top-left to bottom-right (135deg)
→ Horizontal	Left to right
↓ Vertical	Top to bottom
↗️ Diagonal Up	Bottom-left to top-right (45deg)

Widget Position

Where the chat button appears on your website:

• Bottom Right (recommended) - Standard position, doesn't interfere with content
• Bottom Left - Alternative position for RTL sites or preference
• Top Left
• Top Right

Custom Logo

Upload a custom image for the chat button.

Specifications:

• Format: PNG (with transparency) or JPG
• Size: 40x40 pixels recommended
• File size: Under 100KB for best performance

To upload:

1. Click Upload
2. Select or upload an image
3. Click Use this image

---

Content Indexing

The RAG system indexes your website content so the AI can answer questions accurately.

Post Types to Index

Select which content types should be searchable:

• ✅ Posts - Blog posts, articles
• ✅ Pages - Static pages, about, contact
• ✅ Products - WooCommerce products (if installed)

Recommendation: Enable all public content types for comprehensive coverage.

Max Context Chunks

How many content chunks to include in AI context (1-20).

Setting	Trade-off
1-3	Faster, less context
4-6	Balanced (recommended)
7-10	More context, slower
11-20	Maximum context, slowest

Default: 5 chunks

Chunk Size (Words)

Number of words per content chunk (100-2000).

• Smaller chunks (100-300): More precise matching, less context per chunk
• Larger chunks (500-1000): More context, potentially less precise
• Default: 500 words

Chunk Overlap (Words)

Overlap between consecutive chunks for continuity (0-500).

• Why overlap? Ensures important information at chunk boundaries isn't lost
• Default: 100 words

Reindexing Content

Click Reindex All Content to rebuild the content index. Do this after:

• Adding or updating significant content
• Changing indexed post types
• Changing chunk size/overlap settings
• Initial plugin setup

ℹ️ Reindexing may take several minutes for large sites.

---

WooCommerce Integration

If WooCommerce is installed, additional features become available.

Enable Shopping Assistant

When enabled, the chatbot can:

• 🛒 View cart contents - See what items are in the customer's cart
• ➕ Add products - Add items to cart via chat
• ➖ Remove products - Remove items from cart
• 🎫 Apply coupons - Apply discount codes
• 📦 Product information - Provide details about products
• 💡 Recommendations - Suggest relevant products

Example Conversations

Adding to cart:

User: Add this product to my cart
Bot: ✓ Added "Product Name" to your cart. Your cart now has 2 items.

Applying coupon:

User: I have a discount code SAVE20
Bot: ✓ Coupon "SAVE20" applied! You're saving 20% on your order.

Product questions:

User: Is this in stock?
Bot: Yes! The "Product Name" is currently in stock with 15 units available. 
     The price is $49.99. Would you like me to add it to your cart?

---

Features

Multi-Language Support

The chatbot automatically detects and responds in the user's language.

Supported Languages for cart:

• 🇬🇧 English
• 🇫🇷 Français
• 🇩🇪 Deutsch
• 🇪🇸 Español
• 🇮🇹 Italiano

How it works:

1. User sends a message in their language
2. AI detects the language
3. Response is generated in the same language

Page Context Awareness

The chatbot knows which page the visitor is currently viewing.

Example:

User: Can you summarize this page?
Bot: You're viewing our "About Us" page. This page explains our company 
     history, founded in 2010, our mission to provide quality products, 
     and introduces our team of 50+ employees...

Conversation History

• Chat history is preserved during the session
• AI remembers context from earlier messages
• Users can clear history with the 🗑️ button

Source Citations

When answering from indexed content, the chatbot can show sources:

Bot: Our return policy allows returns within 30 days of purchase...

Sources:
• Return Policy
• FAQ - Shipping & Returns

---

How It Works

RAG (Retrieval-Augmented Generation)

┌─────────────────────────────────────────────────────────────┐
│                     User Message                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   1. Intent Detection                        │
│         Determine if it's a chat question or cart action     │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│    Chat Question        │     │     Cart Action         │
└─────────────────────────┘     └─────────────────────────┘
              │                               │
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│ 2. Search Indexed       │     │ 2. Execute Action       │
│    Content (RAG)        │     │    (Add/Remove/etc)     │
└─────────────────────────┘     └─────────────────────────┘
              │                               │
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│ 3. Build Context        │     │ 3. Confirm Action       │
│    + Page Info          │     │    + Update Cart        │
└─────────────────────────┘     └─────────────────────────┘
              │                               │
              ▼                               ▼
┌─────────────────────────────────────────────────────────────┐
│                    4. AI Response                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Display to User                            │
└─────────────────────────────────────────────────────────────┘

Content Indexing Process

1. Extraction: Content is extracted from posts, pages, and products
2. Chunking: Content is split into manageable chunks
3. Storage: Chunks are stored in the database with metadata
4. Retrieval: Relevant chunks are retrieved based on user queries

---

Troubleshooting

Chatbot Not Appearing

Possible causes and solutions:

Cause	Solution
Plugin disabled	Enable in Helvira Chat → General Settings
JavaScript error	Check browser console for errors
Theme conflict	Test with default theme
Caching	Clear site cache and browser cache

"API Key Invalid" Error

1. Verify the API key is correct (no extra spaces)
2. Check if the key has expired
3. Ensure your API account is active
4. Test connection in settings

Chatbot Gives Wrong Answers

1. Reindex content - Click "Reindex All Content"
2. Check indexed post types - Ensure relevant content is indexed
3. Increase max chunks - Allow more context for better answers
4. Review content quality - AI can only use what's indexed

Slow Responses

Cause	Solution
Large chunk size	Reduce chunk size to 300-500
Too many chunks	Reduce max chunks to 3-5
Slow API	Check API status, try different model
Server issues	Check server resources

WooCommerce Cart Actions Not Working

1. Ensure Enable Shopping Assistant is ON
2. Check WooCommerce is active and updated
3. Verify product exists and is in stock
4. Clear WooCommerce transients

Chat History Not Saving

• History is stored in browser sessionStorage
• Clears when browser tab closes (by design)
• Private/Incognito mode may block storage

---

FAQ

General Questions

Q: Is the chatbot free? A: The plugin is free, but requires an API key from Helvira AI which may have associated costs based on usage.

Q: Does it work with any theme? A: Yes, Helvira Chat is designed to work with any properly coded WordPress theme.

Q: Can I use it on multiple sites? A: Check your API key license terms. Some plans allow multiple sites.

Q: Is my data secure? A: Yes. Conversations are processed via secure HTTPS connections. We don't store conversation data on our servers.

Technical Questions

Q: Does it affect site speed? A: The chat widget loads asynchronously and has minimal impact on page load time (~50KB).

Q: Can I customize the AI's personality? A: The AI adapts to your site name and description. Custom system prompts may be available in future versions.

Q: Does it work with page builders? A: Yes, compatible with Elementor, Divi, Beaver Builder, and others.

Q: Can I exclude certain pages? A: Not currently. This feature is planned for a future release.

WooCommerce Questions

Q: Can the chatbot process payments? A: No, it can guide users to checkout but doesn't handle payment processing.

Q: Does it support variable products? A: Yes, it can add variable products with selected variations.

Q: Can it access order history? A: Currently limited. Full order history features are planned.

---

Changelog

Version 1.0.0 (Initial Release)

• ✅ AI-powered chatbot with RAG
• ✅ Content indexing for posts, pages, products
• ✅ WooCommerce integration (cart actions)
• ✅ Multi-language support
• ✅ Customizable appearance (colors, gradients, logo)
• ✅ Mobile responsive design
• ✅ Conversation history
• ✅ Page context awareness
• ✅ Modern admin settings UI

---

Support

Documentation: docs.helvira.ai

Support Email: support@helvira.ai

GitHub Issues: github.com/helvira/chat-plugin/issues

---

License

This plugin is licensed under the GPL v2 or later.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

---

Made with ❤️ by Helvira AI