Hybrid Chatbot Plugin for WooCommerce

An intelligent hybrid chatbot for WooCommerce that combines local search with optional LLM fallback to provide fast, accurate, and cost-effective customer support. Optimized for Greek language but works with any language.

🌟 Features

Core Capabilities

• 🔍 Local Search First - Fast, indexed search across products, pages, posts, and FAQs
• 🤖 LLM Fallback - Optional OpenAI/ChatGPT integration when local search confidence is low
• 🛒 WooCommerce Integration - Automatic product indexing with prices, SKU, stock status, attributes
• 🇬🇷 Greek Language Support - Built-in text normalization, stemming, and stop words
• 🎯 Intent Detection - Recognizes shipping, returns, payment, and product queries
• 💬 Smart Responses - Canned responses for common questions (greetings, hours, contact)

Modes

1. Disabled - Local search only (no LLM)
2. Fallback - LLM only when local confidence < threshold (cost-effective)
3. Always - Full RAG mode, LLM for all queries (best quality)

Privacy & Compliance

• ✅ GDPR compliant with consent collection
• ✅ PII scrubbing (emails, phones, credit cards)
• ✅ Optional conversation logging with retention controls
• ✅ Rate limiting per IP and session
• ✅ Daily LLM spending caps

Admin Features

• 📊 Real-time indexing of products, pages, posts
• ⚙️ Configurable search thresholds and top-k results
• 🎨 Customizable widget colors and position
• 📝 Comprehensive logging and debugging
• 💰 Budget controls for LLM API costs

---

📦 Installation

Method 1: Download from GitHub

1. Download the latest release from Releases
2. Upload to wp-content/plugins/hybrid-chatbot-plugin-for-woo
3. Activate via WordPress Admin → Plugins

Method 2: Clone Repository

cd wp-content/plugins/
git clone https://github.com/yourusername/hybrid-chatbot-woo.git hybrid-chatbot-plugin-for-woo

Requirements

• WordPress 5.8+
• WooCommerce 6.0+
• PHP 7.4+
• MySQL 5.7+ or MariaDB 10.3+

---

🚀 Quick Start

1. Activate Plugin

Go to WordPress Admin → Plugins and activate "Hybrid Chatbot Plugin for WooCommerce"

2. Initial Setup

Navigate to WooCommerce → Chatbot Settings

Basic Settings

• Enable Chatbot: Check to activate
• LLM Mode: Choose Disabled, Fallback, or Always
• Search Threshold: 0.65 (adjust based on results quality)

If Using LLM Mode

• Enable LLM: Check
• OpenAI API Key: Enter your key from OpenAI Platform
• Model: gpt-4 or gpt-3.5-turbo
• Daily Budget: Set max spending (e.g., $5.00)

3. Index Your Content

Click "Reindex All Content" in the admin settings to build the search index.

4. Test the Chatbot

Visit your store homepage - the chat widget should appear in the bottom right corner.

---

🎨 Widget Customization

Appearance Settings

Primary Color: #0073aa (button, header)
Secondary Color: #005177 (hover states)
Position: bottom-right (or bottom-left)

Widget Behavior

• Auto-open on first visit (optional)
• Show/hide toggle button
• Mobile responsive design

---

🧠 How It Works

Local Search (Default)

1. User sends query via chat widget
2. System tokenizes and stems query (Greek-aware)
3. Full-text search against indexed documents
4. Returns top-k results with relevance scores
5. Confidence check: if ≥ threshold, return answer

LLM Fallback Mode

1. If local confidence < threshold
2. Send query + sources to LLM (OpenAI)
3. LLM generates natural response with source links
4. Rate limiting and budget checks applied

Always Mode (RAG)

1. All queries go to LLM
2. Local search provides context documents
3. LLM synthesizes answer from sources
4. Best for complex queries and small talk

---

📋 Supported Content Types

Automatically Indexed

• ✅ WooCommerce Products (title, description, SKU, price, attributes)
• ✅ WordPress Pages
• ✅ WordPress Posts
• ✅ Custom Post Types (configurable)

Product Data Captured

• Product name, SKU, categories, tags
• Regular price, sale price
• Stock status and quantity
• Short & full descriptions
• Product attributes (color, size, etc.)

Manual Updates

Products are reindexed automatically when:

• Product is created/updated
• Stock status changes
• Product is deleted

---

⚙️ Configuration

Admin Settings (WooCommerce → Chatbot Settings)

General Tab

• Enable/disable chatbot
• Widget position and colors
• Auto-open settings

Search Tab

• Search threshold (0.0 - 1.0)
• Top-K results (3-10)
• Snippet character length
• Indexable post types

LLM Tab

• Enable LLM fallback
• API endpoint & key
• Model selection
• Temperature (0.0 - 1.0)
• Max tokens
• Daily budget cap

Privacy Tab

• Enable conversation logging
• Log retention days (1-90)
• PII scrubbing options
• Consent message customization

Rate Limiting Tab

• Requests per minute (chat)
• LLM requests per hour
• IP-based throttling

---

🔧 Advanced Usage

Custom LLM Endpoints

Use any OpenAI-compatible API:

Endpoint: https://your-custom-llm.com/v1/chat/completions
API Key: your-key-here

Canned Responses

Edit in class-search.php → check_canned_responses()

if ( preg_match( '/γεια|hello/iu', $query ) ) {
    return array(
        'answer' => 'Γεια σας! Πώς μπορώ να σας βοηθήσω;',
        'sources' => array(),
        'confidence' => 1.0,
    );
}

Custom Intent Detection

Add to class-search.php → detect_intent()

$custom_keywords = array( 'refund', 'επιστροφή' );
foreach ( $custom_keywords as $keyword ) {
    if ( false !== strpos( $query, $keyword ) ) {
        $intent['type'] = 'refund';
    }
}

---

📊 Database Tables

The plugin creates 3 custom tables:

{prefix}_whc_docs

Stores indexed documents (products, pages, posts)

• doc_id, doc_type, object_id, lang
• title, content, url, meta
• content_hash, indexed_at

{prefix}_whc_index

Full-text search index (tokenized content)

• doc_id, token, freq, positions

{prefix}_whc_conversations (Optional)

Conversation logs (if logging enabled)

• session_id, message_id, role
• message, timestamp

---

🐛 Debugging

Enable Debug Logging

// In wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );

Check logs: wp-content/debug.log

Common Issues

Chatbot Not Appearing

• Check if widget is enabled in settings
• Clear browser cache
• Check for JavaScript console errors

Poor Search Results

• Reindex all content
• Lower search threshold (e.g., 0.50)
• Increase top-k results

LLM Errors

• Verify OpenAI API key is valid
• Check daily budget hasn't been exceeded
• Review error logs for API response

---

🔐 Security

Data Protection

• All API keys stored in WordPress options (encrypted at rest if using secrets)
• PII scrubbing before logging
• Rate limiting prevents abuse
• SQL injection protection via wpdb prepared statements

GDPR Compliance

• Consent collection before chatting
• Right to deletion (clear conversation logs)
• Data retention controls
• Transparent privacy policy

---

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/yourusername/hybrid-chatbot-woo.git
cd hybrid-chatbot-woo
# Make changes and test in local WordPress install

---

📝 Changelog

[0.9.0] - 2026-01-09 (Beta Release)

Added

• Initial beta release
• Local full-text search with Greek language support
• OpenAI/ChatGPT LLM fallback integration
• WooCommerce product auto-indexing
• Three modes: Disabled, Fallback, Always
• Intent detection for shipping, returns, payment queries
• PII scrubbing and GDPR compliance features
• Rate limiting and budget controls
• Customizable chat widget
• Comprehensive admin settings panel
• Conversation logging with retention

Known Issues

• Color/attribute filtering not yet supported in queries
• Limited to Greek and English language stemming
• No multi-language interface (settings in English)

---

📄 License

This project is licensed under the GPL v2 or later - see LICENSE file for details.

---

🙏 Acknowledgments

• OpenAI for ChatGPT API
• WooCommerce team for excellent documentation
• Greek NLP community for stemming resources

---

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

---

🚧 Roadmap

v1.0.0 (Stable Release)

• [ ] Color/attribute filtering in queries
• [ ] Multi-language admin interface
• [ ] Additional language stemmers
• [ ] Analytics dashboard
• [ ] Export conversation logs
• [ ] Product recommendations

v1.1.0

• [ ] Integration with other LLM providers (Claude, Gemini)
• [ ] Voice input support
• [ ] Image recognition for product searches
• [ ] WordPress.org plugin directory submission

---

Made with ❤️ for WooCommerce stores