# Baachal AI Chatbot - WordPress Plugin

[![WordPress Plugin Version](https://img.shields.io/wordpress/plugin/v/baachal-ai-chatbot.svg)](https://wordpress.org/plugins/baachal-ai-chatbot/)
[![WordPress Plugin Downloads](https://img.shields.io/wordpress/plugin/dt/baachal-ai-chatbot.svg)](https://wordpress.org/plugins/baachal-ai-chatbot/)
[![WordPress Plugin Rating](https://img.shields.io/wordpress/plugin/stars/baachal-ai-chatbot.svg)](https://wordpress.org/plugins/baachal-ai-chatbot/)
[![License](https://img.shields.io/badge/license-GPL--2.0%2B-green.svg)](https://www.gnu.org/licenses/gpl-2.0.html)

## Overview

Transform your WordPress website with an intelligent AI chatbot powered by multiple leading AI providers. Baachal AI Chatbot with conversational product search provides instant, accurate responses about your products, services, and content through advanced artificial intelligence with support for Google Gemini, OpenAI ChatGPT, Anthropic Claude, and xAI Grok.

## 🚀 Key Features

### 🤖 Multi-AI Provider Support

- **Google Gemini**: Latest models including Gemini 2.5 Pro/Flash
- **OpenAI ChatGPT**: GPT-5, GPT-4.1, and GPT-4o series
- **Anthropic Claude**: Sonnet 4.5, Opus 4.1, and Haiku 3.5
- **xAI Grok**: Latest Grok-4 Fast models with reasoning capabilities

### 🎨 Enhanced User Experience

- **Modern Color Picker**: Beautiful preset palettes and live color preview
- **Responsive Design**: Perfect experience on all devices
- **Customizable Styling**: Match your brand with advanced theming options
- **Smooth Animations**: Polished interactions and transitions

### 📚 Intelligent Content Awareness

- **Website Content Indexing**: Automatically understands your entire site
- **WooCommerce Deep Integration**: Product knowledge and recommendations
- **Smart Search**: Context-aware responses with relevant product links
- **Real-time Updates**: Dynamic content synchronization

### 🔧 Developer & Admin Features

- **WordPress Standards Compliant**: Follows all WordPress coding best practices
- **Extensible Architecture**: Rich hooks and filters for customization
- **Conversation Management**: Full admin dashboard for chat oversight
- **Performance Optimized**: Intelligent caching and efficient queries

### 🔒 Security & Privacy

- **GDPR Compliant**: Local data control and privacy protection
- **Secure Implementation**: Proper nonce verification and data sanitization
- **Capability Checks**: Role-based access control
- **Safe API Handling**: Secure external API communication

## Installation

### Automatic Installation (Recommended)

1. Go to **Plugins > Add New** in your WordPress admin
2. Search for "Baachal AI Chatbot"
3. Click **Install Now** and then **Activate**
4. Navigate to **Settings > Baachal AI Bot** to configure

### Manual Installation

1. Download the plugin ZIP file
2. Upload and extract to `/wp-content/plugins/baachal/`
3. Activate through the **Plugins** menu in WordPress
4. Go to **Settings > Baachal AI Bot** to configure

## Quick Setup Guide

### 1. Choose Your AI Provider

**Google Gemini** (Recommended for most users)

- Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
- Sign in and create an API key
- Free tier available with generous limits

**OpenAI ChatGPT** (Best for advanced reasoning)

- Visit [OpenAI Platform](https://platform.openai.com/api-keys)
- Create an account and generate API key
- Pay-per-use pricing

**Anthropic Claude** (Excellent for complex tasks)

- Visit [Anthropic Console](https://console.anthropic.com/)
- Sign up and create API key
- Free credits for new users

**xAI Grok** (Latest technology)

- Visit [xAI Console](https://console.x.ai/)
- Create account and generate API key
- Advanced reasoning capabilities

### 2. Plugin Configuration

1. **General Settings**:

   - Enable the chatbot
   - Select your AI provider
   - Enter your API key
   - Choose the AI model
   - Customize chatbot title and welcome message

2. **Styling** (Optional):

   - Choose primary and secondary colors using the enhanced color picker
   - Set chatbot position and size
   - Adjust border radius and font settings
   - Enable/disable animations

3. **WooCommerce** (If applicable):

   - Enable product integration
   - Configure search parameters
   - Set product recommendation limits

4. **Content Indexing** (Recommended):
   - Enable automatic content indexing
   - Select post types to include
   - Configure search relevance settings

## AI Models Available

### Google Gemini Models

- **Gemini 2.5 Pro** - Most advanced for complex reasoning
- **Gemini 2.5 Flash** - Best price-performance balance ⭐ _Recommended_
- **Gemini 2.5 Flash-Lite** - Ultra-fast responses
- **Gemini 2.0 Flash** - Reliable workhorse model
- **Gemini 2.0 Flash-Lite** - Small and efficient

### OpenAI Models

- **GPT-5** - Latest flagship model ⭐ _Recommended_
- **GPT-5 Pro** - Enhanced precision and reasoning
- **GPT-5 Mini** - Cost-efficient option
- **GPT-5 Nano** - Fastest responses
- **GPT-4.1** - Smartest non-reasoning model
- **GPT-4o** - Previous generation flagship

### Anthropic Claude Models

- **Claude Sonnet 4.5** - Best for complex tasks ⭐ _Recommended_
- **Claude Opus 4.1** - Exceptional reasoning capabilities
- **Claude Sonnet 4** - High-performance model
- **Claude Sonnet 3.7** - Extended thinking capabilities
- **Claude Haiku 3.5** - Fastest Claude model

### xAI Grok Models

- **Grok 4 Fast** - Latest model with reasoning ⭐ _Recommended_
- **Grok 4 Fast Reasoning** - Enhanced thinking process
- **Grok 4 Fast Non-Reasoning** - Direct, fast responses

## Usage

### For Website Visitors

1. **Starting a Conversation**:

   - Click the floating chatbot icon (usually bottom-right)
   - Type your question in the input field
   - Press Enter or click the send button

2. **Getting Product Information** (WooCommerce sites):

   - Ask about specific products: "Tell me about your laptops"
   - Request recommendations: "What's the best phone under $500?"
   - Get product details: "Does the iPhone 15 come in blue?"

3. **Website Navigation Help**:

   - Ask about services: "What services do you offer?"
   - Find information: "How do I contact support?"
   - Get directions: "Where are your locations?"

4. **Managing Conversations**:
   - View message history (if enabled)
   - Clear conversation using the trash icon
   - Minimize/maximize the chat window

### For Administrators

1. **Monitoring Conversations**:

   - Visit **Tools > Baachal Conversations**
   - View all customer interactions
   - See conversation details and metadata

2. **Managing Settings**:

   - **General Tab**: Basic configuration and AI settings
   - **WooCommerce Tab**: Product integration settings
   - **Content Tab**: Website indexing configuration
   - **UI Styling Tab**: Appearance customization
   - **Advanced Tab**: Performance and debugging options

3. **Performance Optimization**:
   - Monitor API usage and costs
   - Configure caching settings
   - Adjust content indexing frequency
   - Enable/disable debug mode for troubleshooting

## Advanced Features

### Content Indexing System

The plugin automatically indexes your website content to provide contextual responses:

- **Post Types**: Pages, posts, custom post types
- **WooCommerce**: Products, categories, attributes
- **Search Optimization**: Weighted relevance scoring
- **Cache Management**: Intelligent cache invalidation
- **Performance**: Background processing for large sites

### WooCommerce Integration

Deep integration with WooCommerce provides:

- **Product Knowledge**: Prices, descriptions, availability
- **Category Awareness**: Product organization and filtering
- **Attribute Support**: Colors, sizes, materials, etc.
- **Inventory Status**: Stock levels and availability
- **Clickable Links**: Direct product page navigation

### Developer Features

Extensive hook system for customization:

```php
// Modify AI response before display
add_filter('baachal_bot_response', 'custom_response_handler', 10, 3);

// Add custom context to AI prompts
add_filter('baachal_api_params', 'add_custom_context', 10, 2);

// Handle custom message types
add_filter('baachal_custom_message_handler', 'handle_special_commands', 10, 3);

// Modify chatbot visibility
add_filter('baachal_is_enabled', 'conditional_chatbot_display');
```

### Security Features

- **Input Sanitization**: All user inputs are properly sanitized
- **Output Escaping**: Safe HTML output with XSS protection
- **Nonce Verification**: CSRF protection for all AJAX requests
- **Capability Checks**: Role-based access to admin features
- **Rate Limiting**: Protection against API abuse

## File Structure

```
baachal/
├── baachal.php                    # Main plugin file with multi-AI support
├── uninstall.php                  # Plugin cleanup and data removal
├── README.md                      # Comprehensive documentation
├── readme.txt                     # WordPress.org repository format
├── CHANGELOG.md                   # Version history and updates
├── DEVELOPER_HOOKS.md             # Developer API documentation
├── admin/
│   ├── settings-page.php          # Tabbed admin interface
│   └── tabs/
│       ├── general.php             # Multi-provider AI settings
│       ├── woocommerce.php         # E-commerce integration
│       ├── search.php              # Product search optimization
│       ├── content.php             # Content indexing controls
│       ├── styling.php             # Enhanced UI customization
│       └── advanced.php            # Performance and debugging
├── assets/
│   ├── chatbot.css                 # Frontend responsive styles
│   ├── chatbot.js                  # Interactive chat functionality
│   ├── admin.css                   # Enhanced admin interface styles
│   ├── admin.js                    # Advanced admin interactions
│   ├── images/                     # Plugin icons and graphics
│   └── plugin-assets/              # WordPress.org banner assets
├── includes/
│   └── content-indexer.php         # Intelligent content indexing
├── languages/
│   └── baachal.pot                 # Translation template
└── templates/
    └── chatbot-widget.php          # Responsive chat widget
```

## Customization

### Color Themes

Use the enhanced color picker in **UI Styling** tab:

- **Primary Color**: Headers, buttons, links, accents
- **Secondary Color**: Backgrounds, message bubbles, secondary elements
- **Preset Palettes**: Curated color combinations
- **Live Preview**: See changes in real-time

### Advanced Styling

```css
/* Custom CSS for advanced styling */
.chatbot-container {
  /* Your custom styles */
}

.chatbot-message {
  /* Message styling */
}

.chatbot-header {
  /* Header customization */
}
```

### JavaScript Customization

```javascript
// Custom chat behavior
jQuery(document).ready(function ($) {
  // Your custom interactions
});
```

## Troubleshooting

### Common Issues

**Chatbot Not Appearing**

- ✅ Plugin activated and enabled in settings
- ✅ API key configured correctly
- ✅ No JavaScript errors in console
- ✅ Theme includes `wp_footer()` hook

**AI Not Responding**

- ✅ API key valid and has quota
- ✅ Website can make external requests
- ✅ Selected model is available
- ✅ No network connectivity issues

**WooCommerce Integration Issues**

- ✅ WooCommerce active with published products
- ✅ Integration enabled in plugin settings
- ✅ Products have proper categories and pricing
- ✅ Content indexing is working

**Performance Issues**

- ✅ Enable caching for large product catalogs
- ✅ Optimize content indexing frequency
- ✅ Choose appropriate AI model for traffic
- ✅ Monitor API usage and costs

### Debug Mode

Enable debug mode in **Advanced Settings** for detailed logging:

- API request/response details
- Content indexing status
- Performance metrics
- Error tracking

## Changelog

### Version 1.0.0 - January 15, 2025

#### 🚀 Major Features

- ✨ **Multi-AI Provider Support**: Google Gemini, OpenAI ChatGPT, Anthropic Claude, xAI Grok
- 🤖 **Latest AI Models**: GPT-5, Claude Sonnet 4.5, Grok-4 Fast, Gemini 2.5 Pro/Flash
- 🎨 **Enhanced Color Picker**: Modern UI with preset palettes and live preview
- � **Intelligent Content Indexing**: Advanced website content understanding
- 🛒 **Deep WooCommerce Integration**: Product recommendations and inventory awareness

#### �🔧 Technical Improvements

- 🛡️ **WordPress Standards Compliance**: Full coding standards adherence
- 🚀 **Performance Optimizations**: Intelligent caching and efficient queries
- � **Enhanced Security**: Proper sanitization, nonce verification, capability checks
- 📱 **Responsive Design**: Perfect mobile experience
- 🔧 **Developer Hooks**: Extensive filter and action system

#### 🎨 UI/UX Enhancements

- 🎯 **Modern Admin Interface**: Tabbed settings with dynamic provider switching
- 🎨 **Color Picker Redesign**: Beautiful presets and intuitive color selection
- 📱 **Mobile Optimization**: Enhanced responsive design
- ✨ **Smooth Animations**: Polished interactions and transitions

#### � Bug Fixes

- Fixed undefined variable warnings in settings
- Resolved model selection persistence issues
- Corrected API key validation across providers
- Fixed color picker synchronization

#### � Documentation

- Comprehensive setup guides for all AI providers
- Complete API documentation for developers
- Enhanced troubleshooting guides
- Performance optimization recommendations

## Support & Contributing

For support, feature requests, or bug reports:

- 📧 Email: support@shojibkhan.com
- 🌐 Website: [https://www.shojibkhan.com](https://www.shojibkhan.com)
- 📖 Documentation: Plugin settings pages include contextual help

## Author

**Shojib Khan**  
Full-Stack Developer & WordPress Expert  
Website: [https://www.shojibkhan.com](https://www.shojibkhan.com)

## 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, version 2, as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
```