document

document

NVT AI Chatbot – RAG & Live Chat is a professional WordPress plugin designed to deploy AI chatbots powered by your website’s own data. It seamlessly combines AI automation with Live Chat capabilities and supports advanced E-commerce workflows—including product search, cart management, order tracking, and checkout guidance—specifically optimized for WooCommerce.

The plugin features a comprehensive administration interface with tabs for: Dashboard, Account, Settings, Data Sources, Inbox, Playground, and Feedback.

Dashboard NVT AI Chat Rag

Dashboard v1.1.10

1. What is this plugin for?

The plugin is designed to address three primary business needs:

  • AI Chatbot via Private Knowledge Base: The plugin can crawl website content and index uploaded documents. It answers user queries based on your specific knowledge base using a RAG (Retrieval-Augmented Generation) hybrid mechanism (Qdrant, dense + sparse embeddings, and a reranker) to ensure high precision.

  • Live Chat & Human Handover: Users can request to speak with a human agent at any time. Admins receive real-time notifications via the Inbox tab to take over conversations and can hand the session back to the AI when finished.

  • WooCommerce Integration: For e-commerce sites, the bot can suggest products, add items to the cart, read/update cart contents, track orders, and provide dynamic checkout assistance based on the website’s specific requirements.

2. System Requirements

Minimum Requirements:

  • WordPress: 5.8 or higher

  • PHP: 7.4 or higher

  • Plugin Name: NVT AI Chatbot – RAG & Live Chat

  • Current Version: 1.1.11

Backend/Server Stack:

The system utilizes a high-performance backend architecture:

  • Framework: FastAPI

  • Database: PostgreSQL & Redis

  • Real-time: Socket.IO

  • Vector Database: Qdrant

  • Embedding Model: BAAI/bge-m3

  • Reranker Model: BAAI/bge-reranker-base

Note: Standard users do not need to configure these backend components manually, provided the SaaS/Backend server is operational.

3. Operational Architecture

The system consists of two primary components:

Part 1: WordPress Plugin

Responsible for rendering the frontend widget, providing the Admin UI, storing chat sessions in the WordPress database, syncing cart/order context, and handling REST/AJAX requests. It registers shortcodes, Gutenberg blocks, and REST routes within the core class.

Part 2: AI/Live Chat Server

Handles the core logic: intent classification, RAG execution, WooCommerce tool orchestration, and chitchat. It also manages Socket.IO for real-time communication between users and agents.

Workflow Summary:

  1. User opens the widget.

  2. The widget sends the session ID, user context, page context, and cart snapshot to the server.

  3. The server classifies intent using a “docs-first” strategy (prioritizing knowledge base retrieval over commerce flows unless a clear purchase intent is detected).

  4. If the query is knowledge-based, RAG is triggered.

  5. If the query relates to products/orders, WooCommerce tools are called.

  6. If Live Chat is requested, the session enters “Live Mode” for human intervention.

4. Installation

Upon activation, the plugin runs an activation function to create the necessary database schema and redirects the admin to the Account tab for initial configuration.

Core Database Tables:

  • nvtrag_chat_logs: Stores chat history.

  • nvtrag_chat_sessions: Manages active sessions and bot/live modes.

  • nvtrag_chat_session_meta: Stores metadata (viewed pages, cart snapshots, URLs).

5. Initial Setup (Setup Wizard)

If the setup is incomplete, a 2-step Setup Wizard appears:

  1. Step 1: Register or Enter API Key: Create a new account via email/password or paste an existing API key.

  2. Step 2: Quick Start: After connecting, the wizard guides you to add data via Data Sources and customize the widget in Settings.

6. Admin Interface Overview

  • Dashboard: High-level metrics (Active Sessions, Unread Messages, AI Answers, Quota usage, and activity charts).

  • Account: Manage API keys, view plan status, expiry dates, and upgrade options (PayPal/PayOS).

  • Settings: Configure API endpoints, widget behavior, appearance, and positioning.

  • Data Sources: Manage website crawling, file uploads (PDF, DOCX, etc.), and indexing schedules.

  • Inbox: The command center for live chat agents to manage real-time conversations.

  • Playground: Test the AI’s responses against your indexed data in a sandbox environment.

  • Feedback: Submit bug reports or suggestions with file attachment support.

7. Configuration Settings

7.1 General & API

Configure your API Key, Timezone, and Notification Email. You can also set custom SaaS/WebSocket endpoints. Use the Test Connection button to verify the link to the server.

7.2 Widget Behavior

  • Auto Display: Toggle automatic injection.

  • History: Enable/disable saving chat history.

  • Operating Mode: Choose between Schedule, Always Live, or Always Bot.

  • Availability: Set specific days and hours for live chat support (Default: Mon-Fri, 08:00–17:00 ICT).

  • Display Logic: Select specific post types or pages where the widget should appear.

7.3 Appearance & Positioning

Customize the Light/Dark theme, button styles, colors, custom icons, and corner rounding. You can also set custom avatars for the bot and support agents. Positioning allows for fine-tuning on both Desktop and Mobile devices.

8. Frontend Implementation

To maintain performance, assets are only loaded when necessary. You can display the widget via:

  1. Auto Injection: Enabled in Settings.

  2. Shortcode:

    Chat with us
    Assistant

  3. Gutenberg Block: The “Chat Widget” block.

9. Widget Features

  • Mode Switching: Users can toggle between “Meet a Consultant” and “Exit Live” directly in the header.

  • Persistence: Sessions, history, and widget position are saved in localStorage/sessionStorage.

  • Drag & Drop: Both the icon and the expanded chat window can be moved.

  • Profile Gate: For sensitive actions (Live Chat, file uploads, voice notes), the widget requires a Full Name and Phone Number.

  • File & Voice Support: Supports uploads (PDF, DOCX, ZIP, etc.) and voice messages via the MediaRecorder API (WEBM).

  • Notifications: Audible alerts for incoming messages (configurable).

10. Data Sources & RAG Connectivity

This is the core of your “Internal Knowledge” AI.

  • Web Crawling: Ingest website URLs to extract content. The system tracks chunks, index time, and status.

  • File Indexing: Batch upload files (PDF, DOCX, TXT, CSV, XLS, PPTX) to be converted into vector embeddings.

  • Schedules: Set automated re-crawling via WordPress Cron.

11. AI Logic & Intent Routing

The server uses an advanced Router to classify user intent into: rag_info, product_lookup, order_lookup, chitchat, etc.

  • Docs-First Strategy: The system prioritizes your knowledge base. It avoids “pushing” sales unless the user specifically asks about products or checkout.

  • Hybrid RAG: Combines Dense Vectors (semantic meaning) with Sparse Vectors (keyword matching) and a Reranker for maximum accuracy.

  • SSE Streaming: Responses are sent via Server-Sent Events for a real-time “typing” effect.

12. Inbox – Live Chat Management

Admins use the Inbox to handle human support requests.

  • Management: Filter by date, search sessions, and view unread badges.

  • Context Panel: View user details (Name, Phone, Email), last seen URL, browsing history, cart snapshot, and recent orders.

  • Takeover: Seamlessly switch from Bot to Live and back.

  • Export: Download individual sessions or the entire chat history.

13. WooCommerce Features

  • Product Suggestions: AI searches the catalog and displays product cards.

  • Interactive Cart: Users can add/remove items, update quantities, and view totals directly inside the chat UI.

  • Order Tracking: Secure lookup via email/phone/user ID.

  • Dynamic Checkout: The AI fetches the specific checkout requirements of your site (Guest checkout, required fields, payment methods) and collects missing information in a streamlined, single-message format.

14. FAQ

  • Chatbot not appearing? Check “Auto Display” in Settings or ensure the current page type is allowed.

  • Where to enter the API Key? Use the Setup Wizard or the Account/Settings tabs.

  • Live Chat is inactive? Verify your “Operating Mode” and the “Work Schedule” in Settings.

  • Bot can’t find orders? Ensure the user has provided an email/phone number or is logged in.

  • File upload failed? Ensure the file is under 5MB and matches the allowed formats (PDF, Image, Doc, etc.).