Documentation

Overview

Sellora AI is a production-grade WordPress plugin that adds an AI-powered floating chat widget to any WooCommerce store. Customers type naturally and receive instant, grounded product recommendations — no hallucinated products.

It supports three AI providers switchable at any time, a rule-based Quick Reply engine that bypasses the AI for common queries, MCP tool-calling mode for on-demand product lookups, personalisation, upsell/cross-sell intelligence, and a full admin dashboard.

Multi-Provider AI

Switch providers from Sellora AI → Settings → General. All providers enforce a max_tokens cap of 1024 per request.

Two Operating Modes

Requirements

Installation

Option A — Upload via WordPress Admin

Option B — Manual (FTP / SFTP)

1. Extract the zip on your local machine.
2. Upload the woocommerce-ai-chatbot-sellora/ folder to /wp-content/plugins/.
3. Go to Plugins → Installed Plugins and activate Sellora AI.

Option C — Clone from Git

cd /path/to/wordpress/wp-content/plugins
git clone https://github.com/your-org/woocommerce-ai-chatbot-sellora.git

Configuration

Step 1 — Choose your AI provider

Go to Sellora AI → Settings → General. From the AI provider dropdown, select OpenAI, Claude (Anthropic), or Gemini (Google). The credential fields update instantly.

Step 2 — Get your API key

OpenAI

1. Visit platform.openai.com/api-keys and create a new secret key.
2. Paste it into OpenAI API key in the settings.

Claude (Anthropic)

1. Visit console.anthropic.com/account/keys and create a key.
2. Paste it into Anthropic API key in the settings.

Gemini (Google)

1. Visit aistudio.google.com/app/apikey and create a key.
2. Paste it into Google AI Studio API key in the settings.

Step 3 — Configure the widget

On the General tab: set max message length (default 200), response temperature (recommended 0.3–0.5), and catalog products in context (1–10, default 4).

On the Widget tab: set panel title, subtitle, logo, avatar, launcher icon, and welcome message. Tick Enable widget and save.

Step 4 — Customise colours

On the Appearance tab, 24 colour pickers cover accent, panel, header, messages, input, and typing indicator. Leave any field blank to use the built-in default.

Step 5 — AI Intelligence (optional)

• Enable MCP tool calling — AI fetches products via tool calls on demand. Reduces token cost.
• Max products per tool call — 1–10 (default 5).
• Enable personalisation — exposes get_user_context tool. Requires MCP mode.
• Enable upsell / cross-sell — exposes get_related_products tool. Requires MCP mode.

Admin Pages

Chat History

Sellora AI → Chat History — all sessions grouped by session ID. Filter by IP, name, or date. Click any session for the full conversation thread.

Enquiries

Sellora AI → Enquiries — all enquiry form submissions. Filter by name, email, or date.

IP Blocklist

Sellora AI → IP Blocklist — add exact IPs (203.0.113.45), IPv6, or CIDR ranges (203.0.113.0/24). Enforced entirely server-side.

Quick Replies

Sellora AI → Quick Replies — 69 default rules seeded on activation. Match types: contains or exact. Priority-ordered, 1-hour cache.

Top Requests

Sellora AI → Top Requests — most frequent queries with type badges, inline save-as-Quick-Reply, and CSV export. Popular queries (≥100 hits) flagged with 🔥.

AI Error Log

Sellora AI → AI Error Log — provider failures: No Response (hard fail), MCP Fallback, Legacy Fallback. Admin-only; never shown to customers.

Plugin Guide

Sellora AI → Plugin Guide — in-dashboard documentation covering every feature.

Settings

Security

Request Pipeline

IP Blocklist Details

• Stored in WordPress option aiwoo_blocked_ips (autoload disabled). Max 500 entries.
• IPv4 CIDR: ip2long bitwise mask. IPv6 CIDR: inet_pton binary comparison.
• Always uses $_SERVER['REMOTE_ADDR'] — X-Forwarded-For never trusted.

Developer Notes

Adding a new AI provider

Create includes/class-aiwoo-assistant-{name}-provider.php implementing Provider_Interface, register it in api-handler.php, add it to $allowed_providers in Settings, and add an <option> in the settings UI.

namespace AIWooAssistant;

final class My_Provider implements Provider_Interface {
    public function generate_response( array $payload ) {
        // $payload['instructions'] = system prompt
        // $payload['input']        = user message + context
        // return string
    }
}

CSS Colour System

All widget colours are CSS custom properties on .aiwoo-widget, injected via wp_add_inline_style. No JavaScript involved.

.aiwoo-widget {
    --aiwoo-primary:        #9a162d;
    --aiwoo-header-bg:      var(--aiwoo-primary);
    --aiwoo-user-bubble-bg: var(--aiwoo-primary);
    /* 18 total variables */
}

Token Efficiency

• Trimmed system prompts; slim product context (drops SKU, tags, categories).
• History capped at 6 entries stored, 4 sent; replies reduced to first sentence.
• MCP mode: AI fetches data on demand; 120s transient cache; max 5 API rounds.
• Quick Reply bypass skips the AI entirely (1-hour cache).
• All providers capped at max_tokens = 1024.

Lazy Loading

Only Settings and IP_Blocker are instantiated eagerly. All other services are built on first use — keeping frontend page load overhead to 2–3 objects.

Coding Conventions

• Namespace: AIWooAssistant — Class files: class-aiwoo-assistant-{name}.php
• Text domain: ai-woocommerce-assistant
• Every PHP file: defined( 'ABSPATH' ) || exit;
• WordPress coding standards — spaces, snake_case, Yoda conditions.
• No Composer, no npm, no build step.

Project Structure

woocommerce-ai-chatbot-sellora/
├── woocommerce-ai-chatbot-sellora.php
├── uninstall.php
├── includes/
│   ├── class-aiwoo-assistant-plugin.php
│   ├── class-aiwoo-assistant-settings.php
│   ├── class-aiwoo-assistant-ajax-controller.php
│   ├── class-aiwoo-assistant-chat-service.php
│   ├── class-aiwoo-assistant-catalog-service.php
│   ├── class-aiwoo-assistant-mcp-tools.php
│   ├── class-aiwoo-assistant-openai-provider.php
│   ├── class-aiwoo-assistant-claude-provider.php
│   ├── class-aiwoo-assistant-gemini-provider.php
│   └── api-handler.php
├── admin/
│   ├── settings-page.php
│   ├── chat-history-page.php
│   ├── quick-replies-page.php
│   ├── top-requests-page.php
│   └── ai-errors-page.php
├── templates/
│   └── chat-widget.php
└── assets/
    ├── css/style.css
    └── js/chat.js

Changelog

v1.0.0 Latest

• OpenAI, Claude, and Gemini provider integrations with MCP tool-calling support.
• Floating chat widget with product cards, enquiry form fallback, and honeypot anti-spam.
• Tabbed settings — 24 colour pickers, corner radius, AI Intelligence tab.
• Chat history, enquiries, IP blocklist, quick replies, top requests, and AI error log admin pages.
• Personalisation and upsell/cross-sell via MCP tool calls.
• Rate limiting (15 req/60s), bot detection, nonce verification, input sanitisation.
• Lazy service loading — 2–3 objects on frontend page load instead of 10.
• ~35–50% token savings via trimmed prompts, slim product data, and history reduction.
• HPOS compatible. Full cleanup in uninstall.php.