A pro-grade, modular, and highly secure AI chatbot engine for WordPress. It supports native function calling, dynamic multi-provider LLM adapters, a searchable global holiday seeder, and advanced prompt engineering controls.
To deliver advanced context-aware assistance and dynamically fetched calendar parameters, this plugin interfaces with the following external services. All data transmitted is limited strictly to the resources required to process requests.
- Service Provider: Nager.Date API (https://date.nager.at)
- Usage: When a site administrator uses the "Seed Global Country Holidays" configuration page to seed special opening hours, the plugin queries this API for public holidays based on the country selected.
- Data Transmitted: No personal, administrative, or visitor data is transmitted. Only the target year and country code are sent.
- Terms of Use: Nager.Date Project Information
Depending on your chosen configuration in the settings panel, this plugin forwards chat prompts to the specified third-party API endpoint to generate conversational answers. No other site files or databases are shared.
- Anthropic API (https://api.anthropic.com): Anthropic Privacy Policy
- Google Gemini API (https://generativelanguage.googleapis.com): Google Privacy Policy
- Groq API (https://api.groq.com): Groq Privacy Policy
- Cerebras API (https://api.cerebras.ai): Cerebras Privacy Policy
- Mistral API (https://docs.mistral.ai/api): Mistral Privacy Policy
Because ClientAI is completely self-hosted and open-source, you don't pay a monthly subscription fee to use it. You only pay for the raw API tokens you consume through providers like Groq or OpenRouter.
Thanks to our localized caching system and keyword-targeted RAG architecture, running costs are incredibly low (often under $1.00/month for standard business sites).
👉 Read the full Transparency Statement & True Cost Estimation Guide to see real-world cost calculations across different web traffic profiles.
This plugin delivers a flexible, robust, and highly secure artificial intelligence assistant to your WordPress website. Built on a clean MVC modular architecture, it separates database logic, front-end visual presentation, and API routing.
The chatbot leverages advanced Strategy A retrieval mechanics (RAG) to digest localized page content dynamically, merging it with custom business FAQ rules, real-time temporal pivots, and deterministic schedule validation via native LLM tool-calling (function calling).
-
Multi-Provider AI Adapters: Integrated connection adapters for Anthropic (Claude), Google AI Studio (Gemini), Groq (Llama), Cerebras, Mistral, and custom self-hosted OpenAI-compatible endpoints (Ollama, LM Studio, etc.).
-
Multi-Language Support: Auto-detect visitor browser language or set a fixed language. The AI responds natively in the specified language, making the chatbot accessible to international audiences without configuration changes.
-
Visitor Feedback: Optional thumbs up/down after each response. Satisfaction rate is displayed in the Dashboard, helping identify which answers need improvement.
-
Conversation History: Full threaded chat transcripts grouped by session. View the complete back-and- forth of any conversation in a chat-bubble interface from the admin area.
-
Deterministic Calendar Tool: Empower the AI to answer business opening-hours questions using the check_calendar function. It supports dynamic weekday/weekend defaults, specific date overrides, and annual recurring dates.
-
Global Holiday Seeder: Connects to the Nager.Date API with a searchable autocomplete country selector. This allows you to automatically pull and seed holidays from any supported country directly into your schedules database.
-
Advanced Prompt Engineering: A toggleable developer panel inside your settings page lets you inspect, edit, and experiment with the sub-prompts coordinating the AI's temporal pivots, tool-calling protocols, and negative constraints. Complete with a secure "Reset Engineering Templates" button.
-
Import / Export Configuration: Backup and restore your entire plugin configuration via the Settings page. Select specific sections to export (General Settings, Calendar & Hours, Advanced Prompt Engineering, Custom Q&A Entries, Custom Model Definitions) to a downloadable JSON file. API keys are securely excluded from exports. Import previously exported files to restore your configuration with a single click.
-
Strategy A Adaptive Context Retrieval (RAG): Intelligently queries site-wide pages using standard WordPress keyword search (
's') combined with a custom question cleaner. This ensures only relevant page digests are served to the AI, preventing bloated token usage. By applying'suppress_filters' => true, it securely indexes orphaned or non-menu pages without theme-level interference. -
Asynchronous Cache Warmer: Includes an admin-side batch compiler. Instead of loading and summarizing pages synchronously during user chats (which causes server timeouts), administrators can warm the entire site-wide cache page-by-page comfortably under API rate limits using a beautiful real-time progress bar and log console.
-
Asynchronous Save/Update Pre-Warming: Automatically triggers a background AI summarization hook whenever an allowed post type is saved or updated in the editor, ensuring your site-wide knowledge base is always pre-warmed and up-to-date.
-
Double-Layered Resiliency: Automatic server-side connection retries on cURL timeouts combined with a client-side 3x recovery loop. If a query lags, an elegant status notice ("⏳ Hang on, still working on it...") is shown to keep visitors engaged, gracefully falling back to standard support channels if a final drop occurs.
-
Custom Q&A Overrides: Prioritized semantic matching table to bypass expensive LLM inference entirely for exact business FAQs and keywords.
-
Accessibility-First Design (WCAG 2.2 AA Principles): Engineered with accessibility as a core priority. The frontend chatbot uses strict keyboard focus management (capturing and returning focus cleanly to the launcher on open/close), a native Escape key closing hook, ARIA landmark and live announcer roles (role="dialog", role="log", aria-live="polite"), and full CSS support for prefers-reduced-motion browser media queries.
Administrator Responsibility Note: While the chatbot's structural engine is built to fully support WCAG 2.2 AA standards, complete compliance on your live website ultimately depends on your administrative choices. Ensure your chosen "Primary Color" under settings maintains a contrast ratio of at least 4.5:1 against white text, and that your custom welcome messages and Q&As remain descriptive, clear, and readable.
-
Enterprise Cryptography & Security: Secure AES-256-GCM database encryption for API keys, strict Server-Side Request Forgery (SSRF) endpoint filters, WP nonce verification, and CDN-aware proxy IP rate limiting.
-
Models Management: A dedicated admin page for managing AI models per provider. Add custom models, edit existing ones, toggle active status, or reset a provider to its default models — all without editing JSON files. Built-in models are seeded from the plugin and automatically updated on upgrade.
-
Audit Logs & Cleanup: Paginated, filterable conversation logging with automated background cron cleanup tasks to manage database storage.
- Download or clone this repository into a folder named client-ai.
- Move the directory to your /wp-content/plugins/ directory.
- Activate Client AI inside your WordPress Plugins screen.
- Go to Client AI > Settings in your WordPress admin menu.
- Select your active AI Provider and input your API credentials.
- Choose your desired model from the dynamic catalog.
- Go to the Knowledge & Persona tab and click Warming Cache / Rebuild Site-wide Summaries to pre-warm your site-wide context database.
- Set your primary brand color, chatbot title, and default welcome message.
- Save your settings.
You can output the chatbot toggle on your site in two ways:
- Automatic Injection: Check the Auto-inject box in Display Options to display the floating widget on all allowed public pages automatically.
- Shortcode: Uncheck Auto-inject and drop this shortcode into any page, text block, header, or footer element:
[ai_chatbot]
Client AI introduces a database-driven Models system accessible via Client AI > Models in the WordPress admin. This replaces the old JSON-only catalog with a flexible, CRUD-capable approach.
- Built-in Models: Automatically seeded from assets/models.json on plugin activation. Marked as "Built-in" and protected from accidental deletion. Legacy "custom-model" seeds have been removed to ensure new custom installations start with a completely clean slate.
- Custom Models: Add your own models for any provider. Enter the model ID exactly as required by the API (e.g.
mistralai/mistral-small-3.1-24b-instruct:freeon OpenRouter), give it a display name, description, and configure tool support. - Custom Endpoints & Keys: When adding a model under the Custom / Self-hosted provider, you can specify a model-specific Base URL Endpoint and Custom API Key. Stored keys are encrypted securely in the database using AES-256-GCM.
- Edit & Toggle: Edit any model's display name, description, context window, and flags. Toggle models active/inactive without deleting them.
- Reset Provider to Defaults: Remove all custom models for a provider and re-seed the factory defaults — useful after experimenting.
- On activation, the plugin creates the wp_aicb_models database table.
- All models from assets/models.json are inserted using INSERT IGNORE — safe to re-run without overwriting custom models.
- The catalog functions (aicb_get_catalog(), aicb_get_providers(), aicb_get_models()) now query the database instead of reading JSON, while falling back to JSON if the table is empty.
- The Settings page completely isolates the Model selection. Selecting the Custom / Self-hosted active provider card allows you to choose your custom-defined model configurations directly from the standard dropdown menu. All confusing, legacy global text inputs (Endpoint URL, Model ID, and API Key) have been completely removed from the Settings screen.
- Custom model API requests are routed dynamically. If a custom model has its own endpoint and API key defined, the plugin automatically decrypts the key and targets the model-specific URL.
- Editing assets/models.json directly no longer has any effect after the first activation. The JSON file serves as the seed source; the database is the authoritative runtime source.
- The is_custom flag (0 = seeded, 1 = user-added) enables clean separation between built-in and custom models.
- The tool-support check in aicb_adapter_openai_compat() now queries the supports_tools column directly instead of relying on fragile string matching against provider names and URLs.
By expanding the 'Advanced Prompt Engineering' panel on the settings page, developers can modify the core instructions guiding the model's behavior:
- Temporal Context Template: Instructs the model on how to handle the current system time and date. Supports {current_date} and {current_time} dynamic tag replacements.
- Tool Coordination Protocol: Teaches the model exactly when to call the calendar tool vs. reading static FAQs, and how to negotiate rule overrides.
- Negative Constraints & Integrity: Governs conversational formatting, strict output length limits, context leak safeguards, and forbidden word exclusions.
If a developer's customizations cause unwanted behavior or system drift, clicking the Reset Engineering Templates button will securely purge custom overrides and restore the factory prompt schemas.
I am working to expand the capabilities of this plugin. Upcoming development priorities, without promises, include:
Introduce a seamless transition from AI-driven conversations to live human support via Discord.
- How it will work: When a user requests to speak with a live person, a bridge will be established directly between the chat interface and your Discord server using the Discord API.
- The Experience: Support agents can respond straight from Discord channels, while the website visitor enjoys a real-time, continuous live chat experience without ever having to leave the chat window.
To keep the core plugin lightweight, advanced features—including the live Discord bridge—will be introduced as optional, modular add-on plugins. This ensures you only install and configure the specific integrations your workflow requires.
This plugin is fully open source and released under the GPL-2.0+ license.
Members of the WordPress community are welcome to clone, fork, modify, and redistribute this codebase, provided that any modified distributions are also kept free, open source, and accessible to the public.
If this Client AI integration saved you development hours, improved your customer experience, or made your site more accessible, please consider buying me a coffee to support my ongoing work and contributions to the open-source community!