Introduction

AI RAG Assistant Pro adds an intelligent floating chat widget to your WordPress site. Unlike basic AI chatbots, it uses Retrieval-Augmented Generation (RAG) to answer questions based on your actual content — not hallucinations.

Requirements

Installation

Method 1 — WordPress Admin Upload

Method 2 — FTP Upload

1. Extract ai-rag-assistant.zip on your computer
2. Upload the ai-rag-assistant folder to /wp-content/plugins/
3. Go to WordPress Admin → Plugins → Installed Plugins
4. Find "AI RAG Assistant Pro" and click "Activate"

Quick Start (5 Minutes)

API Setup

Go to AI Assistant → Settings → API & Model tab.

Settings Explained

Free API Providers

Groq (Recommended Free Option)

100% free, no credit card required, very fast responses.

Google Gemini (Also Free)

OpenAI (Paid — Best Quality)

OpenRouter (Free Models Available)

Vector Embeddings

Go to Settings → Embeddings tab.

When to Enable Embeddings

RAG Configuration

Go to Settings → RAG tab.

Chat Widget

Go to Settings → Widget tab.

Voice Features

Go to Settings → Widget tab → Voice Settings section.

Voice Input (Microphone)

Users click the mic button and speak their question. Speech is converted to text and sent automatically.

Voice Output (Text-to-Speech)

AI responses are read aloud. Users can toggle this via the speaker icon in the widget header.

Requirements for Voice

• HTTPS (SSL certificate) is required for microphone access
• User must grant microphone permission in browser
• Chrome or Edge for best experience

Integrations

These optional integrations extend the assistant with external services and advanced data handling.

WhatsApp Button

Enable a WhatsApp button inside the chat widget and configure the phone number and button text. Visitors can continue conversations in WhatsApp directly.

Pinecone Vector Store

Use Pinecone for external vector storage when your knowledge base grows large. Configure the API key, host, index, and namespace to improve search performance.

Protection & Alerts

The plugin supports honeypot traps, optional CAPTCHA protection, and email alerts for lead capture and critical events.

Knowledge Base

Go to AI Assistant → Knowledge Base.

Full Re-index

Click "Full Re-index" to index all your WordPress content. This:

1. Indexes all published posts (if enabled)
2. Indexes all published pages (if enabled)
3. Indexes selected custom post types
4. Indexes WooCommerce products (if enabled)
5. Generates vector embeddings (if enabled)

Embedding Coverage

The progress bar shows what percentage of chunks have vector embeddings. 100% means semantic search is fully active.

PDF Library

Go to AI Assistant → PDF Library.

Uploading a PDF

1. Drag and drop a PDF onto the upload zone, or click to browse
2. Optionally add a display title and category
3. Click "Upload & Index PDF"
4. Wait for processing to complete
5. AI can now answer questions from the PDF

PDF Requirements

Best PDF Types

• Product manuals and user guides
• FAQ documents
• Company policies and procedures
• Price lists and catalogs
• Terms and conditions
• Technical documentation
• Training materials

Custom Post Types

Go to Settings → RAG tab → Index Custom Post Types.

The plugin automatically detects all registered public custom post types. Check the ones you want to include in the knowledge base.

Supported Plugins

• Advanced Custom Fields (ACF) — all field types supported
• CPT UI — custom post types detected automatically
• Meta Box — fields extracted automatically
• Pods — custom content types supported
• JetEngine — post types detected
• Toolset Types — fully supported
• Any plugin using register_post_type()

Custom Field Support

The following ACF field types are extracted automatically:

• Text, Textarea, WYSIWYG, Number, URL, Email
• Select, Checkbox, Radio, True/False
• Repeater fields (nested content)
• Group fields (nested content)
• Image (extracts alt text and URL)
• Link (extracts title and URL)
• Post Object / Relationship (extracts titles)
• User field (extracts display name)

WooCommerce Integration

Go to Settings → WooCommerce tab. Requires WooCommerce 7.0+.

Lead Capture

Go to AI Assistant → Leads.

Collect contact details and page context from visitors who submit their email or phone number in the chat. Leads are stored in WordPress and can be exported to CSV.

Features

• Capture name, email, phone, and visited page
• Export leads to CSV for CRM import
• View lead timestamps and page URLs
• Use lead capture to grow your sales pipeline

Appointments

Go to Settings → Appointments via the main Settings page.

Enable appointment booking to let visitors request meetings directly from the chat widget. Configure available services, working hours, slot duration, and notification email.

Appointment Settings

• Enable appointment scheduling in the widget
• Set available start and end times
• Choose slot duration in minutes
• Configure services and recipient email notifications
• Integrate with Calendly using your public scheduling URL

Conversations

Go to AI Assistant → Conversations.

View all chat conversations between users and your AI assistant. Features include:

• Full message history viewer
• Token usage tracking
• RAG context indicator (🔍 shows when AI used your content)
• Guest vs logged-in user separation
• Delete individual conversations
• Export all conversations to CSV
• Test API connection button

License Management

Go to AI Assistant → License.

License Tiers

Activating Your License

1. Go to AI Assistant → License
2. Enter your license key in the input field
3. Click "Activate"
4. Features unlock immediately

Security Settings

Go to Settings → Security tab.

Hooks & Filters

Developers can extend plugin behavior using WordPress hooks.

Filters

// Add custom AI models to dropdown
add_filter( 'ai_rag_allowed_models', function( $models ) {
    $models['my-custom-model'] = 'My Custom Model';
    return $models;
});

// Modify messages before sending to AI
add_filter( 'ai_rag_messages', function( $messages, $user_msg ) {
    // Add custom context
    return $messages;
}, 10, 2 );

// Change context chunk count
add_filter( 'ai_rag_context_chunks', fn() => 5 );

// Change chunk overlap
add_filter( 'ai_rag_chunk_overlap', fn() => 100 );

// Modify embedding model
add_filter( 'ai_rag_embedding_model', fn() => 'text-embedding-3-large' );

// Customize welcome message per page
add_filter( 'ai_rag_welcome_message', function( $msg ) {
    if ( is_shop() ) return '🛍️ How can I help you shop?';
    return $msg;
});

// Add suggested questions per page
add_filter( 'ai_rag_suggested_questions', function( $questions ) {
    if ( is_product() ) {
        return [
            'What sizes are available?',
            'What is your return policy?',
            'How long does shipping take?',
        ];
    }
    return $questions;
});

// Change rate limits
add_filter( 'ai_rag_rate_limit',  fn() => 50 );
add_filter( 'ai_rag_rate_window', fn() => 3600 );

// Change indexable post types
add_filter( 'ai_rag_indexable_post_types', function( $types ) {
    $types[] = 'my_custom_type';
    return $types;
});

// Change "Powered by" text
add_filter( 'ai_rag_powered_by', fn() => 'Powered by My Brand' );

// Change data retention days
add_filter( 'ai_rag_conversation_retention_days', fn() => 180 );

Actions

// After plugin activates
add_action( 'ai_rag_assistant_activated', function() {
    // Custom setup code
});

// Daily cleanup hook
add_action( 'ai_rag_cleanup', function() {
    // Custom cleanup logic
});

Troubleshooting

Chat Widget Not Showing

• Make sure you are viewing the frontend of your site, not the admin
• Check that your theme has <?php wp_footer(); ?> before </body>
• Go to Settings → Widget and make sure no specific pages are selected (or the current page is selected)
• Clear all caches (caching plugin, browser, Cloudflare)
• View Page Source and search for ai-rag-widget — if you see a comment explaining why it's hidden, that's your clue

AI Not Answering From My Content

• Go to Knowledge Base and click "Full Re-index"
• Make sure your content has actual text (not just images)
• If using Groq/Gemini, disable Embeddings in Settings — use keyword search instead
• Lower the Similarity Threshold to 0.5 in Settings → Embeddings
• Increase Max Context Chunks to 5

API Connection Failed

• Make sure your API key is saved correctly (click Save Settings first)
• Verify the endpoint URL matches your provider
• Check your API account has billing set up (for paid providers)
• Enable Debug Mode in Settings → Developer and check wp-content/debug.log

PDF Not Being Indexed

• Make sure your PDF is text-based, not scanned
• File must be under 20MB
• Try re-indexing from the PDF Library page
• Install poppler-utils on your server for better extraction

Settings Not Saving

• Check for JavaScript errors in browser console (F12)
• Make sure WordPress nonces are not expired (reload the page)
• Check file permissions on wp-content directory

Frequently Asked Questions

Which AI providers are free?

Groq (best free option — fast, no credit card), Google Gemini (1,500 free requests/day), and OpenRouter (has free models). OpenAI requires a paid account but offers the best quality.

Does it work without an API key?

No. An AI API key is required for the chat to work. However, Groq provides a completely free API key with generous limits.

Will it slow down my website?

No. The chat widget loads asynchronously and does not affect page load time. JavaScript is only loaded on pages where the widget is enabled.

Does it work with caching plugins?

Yes. All AI requests use AJAX (admin-ajax.php) which is excluded from caching by all major caching plugins (WP Rocket, LiteSpeed, W3 Total Cache, etc.).

Can I use it on multiple sites?

The regular license covers 1 site. The Agency license covers unlimited sites.

Is my data sent to third parties?

Chat messages are sent to your chosen AI API provider (OpenAI, Groq, etc.) to generate responses. All conversation data is stored on your own server. We do not collect any data.

Can the AI answer in multiple languages?

Yes! The AI responds in whatever language the user writes in. Configure the voice language in Settings → Widget for voice features.

What happens if the AI API is down?

The plugin handles API errors gracefully and shows a friendly error message to the user. Your site continues to work normally.

Changelog

Version 2.0.0

• ✨ Added vector embeddings with cosine similarity search
• ✨ Full WooCommerce integration (products, orders, cart, recommendations)
• ✨ PDF upload and indexing system
• ✨ Custom post type support with ACF field extraction
• ✨ Voice input and output (Web Speech API)
• ✨ License management system (Free/Starter/Pro/Agency)
• ✨ Lead capture dashboard with CSV export
• ✨ Appointments and Calendly booking support
• ✨ WhatsApp widget integration
• ✨ Pinecone external vector database support
• ✨ Built-in honeypot + CAPTCHA protection
• ✨ Email alerts and developer debug settings
• ✨ Knowledge base admin page with stats
• ✨ Product recommendation cards in chat
• ✅ Improved chunking algorithm
• ✅ Better page detection for block themes
• ✅ Save success messages on settings tabs
• ✅ API test button on settings page

Version 1.0.0

• 🚀 Initial release
• Basic chat widget
• RAG with keyword search
• Conversation history
• Admin settings page

Support

How to Get Support

1. Activate a valid license to unlock the support page
2. Purchase a license for priority support
3. Leave a comment on the Codester item page
4. Include your WordPress version, PHP version, and error description
5. Enable Debug Mode and share relevant log entries

Response Time