Rapls AI Chatbot Manual (Free Edition)

Complete documentation for every setting in the WordPress AI Chatbot plugin.
Version: 1.5.6 | PHP 7.4+ | WordPress 5.8+

Dashboard

The Dashboard is the landing page when you navigate to AI Chatbot in the WordPress admin menu. It provides an at-a-glance overview of your chatbot’s activity, configuration status, and API usage.

Overview

The Dashboard is divided into three main sections: Statistics Cards at the top, a Status panel in the middle, and API Usage Statistics at the bottom. All data updates automatically each time you load the page.

Statistics Cards

Five summary cards are displayed across the top of the Dashboard:

Status Panel

The Status panel shows the current configuration state of key features:

API Usage Statistics (Past 30 Days)

A detailed breakdown of your AI API token usage over the past 30 days:

AI Settings

Configure your AI provider, API keys, models, vector embedding, and MCP server. Navigate to AI Chatbot > Settings > AI Settings tab.

AI Provider

Select the AI service your chatbot will use. Each provider requires its own API key and model selection.

Setting key: ai_provider

Default: openai

OpenAI Settings

Configure your OpenAI API key and model. OpenAI is the default provider and offers the widest range of models.

How to get your OpenAI API key:

1. Go to https://platform.openai.com/api-keys
2. Sign in or create an OpenAI account
3. Click Create new secret key
4. Give it a name (e.g., “WordPress Chatbot”) and click Create secret key
5. Copy the key immediately — it starts with sk- and is shown only once
6. Add billing information under Settings > Billing to enable API access

API Key (openai_api_key) Required: Enter a key starting with sk-. The key is encrypted on save. Use the Test Connection button to verify connectivity. Use the Remove button to delete a saved key.

Model Selection (openai_model):

Claude (Anthropic) Settings

Configure your Anthropic API key and model. Claude excels at following complex instructions and providing nuanced, safe responses.

How to get your Anthropic API key:

1. Go to https://console.anthropic.com/
2. Sign in or create an Anthropic account
3. Navigate to API Keys in the left sidebar
4. Click Create Key
5. Copy the key — it starts with sk-ant-
6. Add billing information under Plans & Billing to enable API usage

API Key (claude_api_key) Required: Enter a key starting with sk-ant-. Encrypted at rest. Test Connection and Remove buttons are available.

Model Selection (claude_model):

Gemini (Google) Settings

Configure your Google AI API key and model. Gemini offers strong multimodal capabilities and a generous free tier.

How to get your Google AI API key:

1. Go to https://aistudio.google.com/apikey
2. Sign in with your Google account
3. Click Create API key
4. Select or create a Google Cloud project
5. Copy the generated API key

API Key (gemini_api_key) Required: Enter your Google AI Studio API key. Encrypted at rest.

Model Selection (gemini_model):

OpenRouter Settings

OpenRouter provides unified API access to 100+ models from multiple providers (OpenAI, Anthropic, Google, Meta, Mistral, and more) through a single API key.

How to get your OpenRouter API key:

1. Go to https://openrouter.ai/keys
2. Sign in or create an OpenRouter account
3. Click Create Key
4. Copy the key — it starts with sk-or-
5. Add credits under Account > Credits to enable API usage

API Key (openrouter_api_key) Required: Enter a key starting with sk-or-. Encrypted at rest.

Model (openrouter_model): The default is openrouter/auto, which automatically selects the best model for each request. Click the refresh button to fetch the full list of available models.

Default: openrouter/auto

Vector Embedding (RAG)

Enables semantic search using AI embeddings for improved knowledge base and site content retrieval. Instead of relying solely on keyword matching, vector search understands the meaning of queries.

How to set up Vector Embedding:

1. Ensure you have a valid API key configured for OpenAI or Gemini (even if your primary AI provider is Claude or OpenRouter)
2. Go to Settings > AI Settings and scroll to the Vector Search section
3. Toggle Vector Search to Enabled
4. Select an Embedding Provider or leave on Auto
5. Save settings
6. If you have existing knowledge base entries or site learning content, run a crawl to generate embeddings

MCP (Model Context Protocol) Server

Enables external AI tools such as Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients to access your site’s knowledge base and conversation data programmatically.

MCP Available Tools:

The MCP server exposes the following tools to connected AI clients:

• search_knowledge — Search your knowledge base Q&A entries
• get_site_info — Retrieve site information (name, URL, description, active theme, plugins)

Claude Desktop Configuration:

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "your-site-name": {
      "url": "https://example.com/wp-json/wp-ai-chatbot/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

On macOS, the config file is located at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it is at %APPDATA%\Claude\claude_desktop_config.json.

Cursor / Windsurf Configuration:

For Cursor, add the MCP server in Settings > MCP Servers. For Windsurf, configure it in the MCP settings panel. Both use the same URL and Authorization header format:

{
  "mcpServers": {
    "wordpress-chatbot": {
      "url": "https://example.com/wp-json/wp-ai-chatbot/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

Chat Settings

Configure how the chatbot behaves, what it says, and how it processes conversations. Navigate to AI Chatbot > Settings > Chat Settings tab.

Bot Name

The display name shown in the chat widget header and next to bot messages.

Setting key: bot_name

Default: Assistant

A Reset button is available to restore the default value.

Bot Avatar

The avatar icon displayed next to bot messages in the chat widget.

Setting key: bot_avatar

Default: Robot emoji

• Emoji: Enter any emoji character directly into the text field (e.g., a robot face, a speech bubble, your brand’s representative emoji).
• Image: Click Select Image to open the WordPress Media Library and choose an image. Recommended size: 96×96 pixels or larger, square aspect ratio. Supported formats: JPG, PNG, GIF, SVG.

Use the Reset to Emoji button to revert to the default emoji avatar.

Welcome Message

The first message displayed when a user opens the chat widget. This is a static greeting shown immediately — it is not sent to the AI.

Setting key: welcome_message

Default: Hello! How can I help you today?

Per-Language Welcome Messages (welcome_messages):

When the Response Language is set to Auto-detect, a collapsible panel appears below the welcome message field where you can configure separate welcome messages for 13 languages:

Priority order:

1. Per-language message — If a specific message is configured for the detected browser language, it is used.
2. Welcome Message — If no per-language message exists, the main welcome message is shown.
3. Built-in default — If the welcome message is unchanged from the default, a built-in translation is used.

Response Language

Controls which language the AI responds in.

Setting key: response_language

System Prompt

The system prompt defines the AI’s behavior, personality, and constraints. It is sent as the first message in every conversation and acts as the AI’s instruction manual.

Setting key: system_prompt

Default: A comprehensive 6-rule prompt covering:

1. ACCURACY: Use reference information as the primary source
2. HONESTY: Clearly state when information is not available
3. NO FABRICATION: Never invent facts, URLs, prices, or dates
4. CONCISENESS: Provide clear, focused answers
5. LANGUAGE: Respond in the same language as the user
6. TONE: Be professional, friendly, and helpful

You can fully customize this prompt. Use the Reset to default button to restore the original.

System Prompt Examples:

E-commerce support bot:

You are the customer support assistant for [Store Name].
- Answer questions about products, shipping, returns, and orders
- Never recommend competitor products
- For order issues, always ask for the order number
- Shipping: Free over $50, standard 3-5 business days, express 1-2 days
- Returns: 30-day return policy, items must be unused
- If you cannot help, suggest contacting support@example.com

SaaS documentation bot:

You are the help assistant for [Product Name].
- Only answer questions about [Product Name] features and usage
- Reference the documentation when possible
- For billing questions, direct users to the billing page at /account/billing
- For bug reports, ask users to submit a ticket at /support
- Never share internal implementation details or roadmap

Restaurant information bot:

You are the virtual concierge for [Restaurant Name].
- Provide information about our menu, hours, and location
- Hours: Mon-Fri 11AM-10PM, Sat-Sun 10AM-11PM
- Location: 123 Main Street, City, State
- Reservations: Link to our booking page at /reservations
- Dietary accommodations: We offer vegan, gluten-free, and nut-free options
- For catering inquiries, suggest emailing catering@example.com

Context Prompts (Advanced)

Customize how knowledge base and site learning data is presented to the AI. These prompts are appended to the system prompt when relevant data is found. This section is collapsed by default — check the checkbox to expand it.

Use {context} as a placeholder for the actual content in all context prompts.

Each prompt has a Reset to default button to restore the original text.

Feature Prompts (Advanced)

Customize the behavior of regeneration, feedback learning, and summary features. This section is collapsed by default — check the checkbox to expand it.

Regenerate Prompt Placeholders:

Each prompt has a Reset to default button to restore the original text.

Message History Count

Number of previous messages sent to the AI as context. More messages give the AI better conversational context but increase token usage and API costs.

Setting key: message_history_count

Default: 10 | Range: 1 – 50

A Reset button is available to restore the default value.

Max Tokens

Maximum number of tokens the AI can generate in a single response. One token is approximately 4 English characters or 1-2 characters in Japanese/Chinese/Korean.

Setting key: max_tokens

Default: 1000 | Range: 100 – 4000

A Reset button is available to restore the default value.

Token estimation guide:

GPT-5 and Reasoning Model Auto-Multiplier:

For GPT-5 and reasoning models (o1, o3-mini), the configured max tokens value is automatically multiplied to account for internal reasoning tokens. The default multiplier is x4, so a setting of 1000 becomes approximately 4000 effective tokens. Adjust the multiplier via the wpaic_gpt5_token_multiplier filter (range: 1-8). Higher multipliers improve response completeness but increase API costs.

Temperature (Creativity)

Controls response randomness. Lower values produce consistent, deterministic answers; higher values produce creative, varied responses.

Setting key: temperature

Default: 0.7 | Range: 0 – 2 (step 0.1)

A Reset button is available to restore the default value.

Feedback Buttons

Displays thumbs-up and thumbs-down buttons below each AI response for users to rate quality.

Setting key: show_feedback_buttons

Enabled: Feedback buttons appear on every bot message. Positive and negative feedback are stored in the database and used in future prompts (see Feature Prompts) to improve response quality over time.

Disabled: No feedback buttons are shown. Users cannot rate responses.

Default: Disabled

API Quota Error Message

The message displayed to users when the AI provider’s API quota is exceeded or a billing issue occurs (e.g., you have run out of API credits).

Setting key: quota_error_message

Default: Currently recharging. Please try again later.

A Reset button is available to restore the default text.

Web Search

When the knowledge base does not contain a sufficient answer, the AI can automatically search the web in real time to provide up-to-date information.

Setting key: web_search_enabled

Enabled: The AI performs web searches when needed, providing up-to-date information from the internet. This is useful for questions about current events, live pricing, or information not in your knowledge base.

Disabled: The AI relies solely on its training data and your knowledge base/site learning content.

Default: Disabled

Display Settings

Control the visual appearance and placement of the chat widget. Navigate to AI Chatbot > Settings > Display Settings tab.

Widget Theme

Select the visual theme for the chat widget. Each theme sets a coordinated color scheme and visual style for the header, messages, input area, and badge button.

Setting key: widget_theme

Default: default

Free Themes (6):

Pro Themes (10): PRO

The Pro edition adds 10 additional themes: Modern, Gradient, Dark, Glass, Rounded, Ocean, Sunset, Forest, Neon, and Elegant. These are shown in the settings UI with a lock icon and cannot be selected without the Pro plugin. Each Pro theme is designed for specific aesthetics and branding needs.

Primary Color

The main accent color used for the chat header, send button, badge button, and user message bubbles. A color picker widget is provided.

Setting key: primary_color

Default: #007bff (blue)

A Reset button restores the default color. Note that selecting a theme automatically sets a matching color, but you can override it afterwards.

Secondary Color

An additional accent color used for secondary UI elements. The exact usage depends on the selected theme.

Setting key: secondary_color

Default: Varies by theme

A color picker widget is provided. A Reset button restores the theme default.

Dark Mode PRO

Enables a dark color scheme overlay on the chat widget, regardless of the selected theme.

Setting key: dark_mode

Enabled: The chat widget uses dark backgrounds with light text. Works with any theme as an overlay.

Disabled: The widget uses standard light-mode colors from the selected theme.

Default: Disabled

This feature requires the Pro plugin. The setting is visible but disabled (locked) in the Free edition.

Badge Position

Controls where the floating chat badge button is positioned on the page. A visual grid selector lets you pick one of four corners.

Setting key: badge_position

Badge Margins (badge_margin_right, badge_margin_bottom):

Fine-tune the distance from the viewport edge. Margin labels dynamically change based on the selected position (e.g., “Right” and “Bottom” for bottom-right, “Left” and “Top” for top-left).

A Reset button restores both margins to 20px.

Badge Icon PRO

Customize the icon displayed inside the floating chat badge button.

The Free edition shows a default chat bubble SVG icon. A preview is displayed in the settings. The Pro edition allows four icon types:

• Default: Built-in chat bubble icon (SVG)
• Preset: Choose from a library of preset SVG icons
• Image: Upload a custom image from the Media Library
• Emoji: Use any emoji character

Badge icon customization is configured in Pro Settings > CUSTOMER > Badge Icon when the Pro plugin is active.

Markdown Rendering

Controls whether AI responses are rendered with Markdown formatting. The plugin includes a built-in Markdown parser (no external libraries required).

Setting key: markdown_enabled

Enabled: Bold, italic, code blocks, inline code, ordered/unordered lists, headings, and links are rendered as formatted HTML in bot messages.

Disabled: Bot messages display as plain text. Markdown syntax characters appear literally.

Default: Enabled

Supported Markdown syntax:

Typing Indicator

Shows an animated typing indicator (three bouncing dots) while the AI is generating a response, giving users visual feedback that their message is being processed.

Setting key: typing_indicator

Enabled: Typing animation appears while waiting for the AI response.

Disabled: No visual feedback during AI processing (the response simply appears when ready).

Default: Enabled

Max Input Length

Maximum number of characters a user can type in a single message. This helps prevent excessively long messages that consume large amounts of tokens.

Setting key: max_input_length

Default: 1000 characters | Range: 100 – 10000

A character counter is displayed to the user as they type, showing remaining characters.

Mobile Display

Controls whether the chat widget appears on mobile devices (screen width below 768px).

Setting key: show_on_mobile

Enabled: The chat widget is displayed on mobile devices. On small screens, the chat window expands to fill the viewport for a better user experience.

Disabled: The chat widget (both badge and window) is completely hidden on mobile devices.

Default: Enabled

Page Visibility

Fine-grained control over which types of pages display the chatbot.

Include Only IDs (badge_include_ids):

Comma-separated post/page IDs. When set, the chatbot is displayed only on these specific pages, overriding the page type checkboxes above. Leave empty to use page type settings.

Example: 10, 25, 142

Exclude IDs (badge_exclude_ids):

Comma-separated post/page IDs where the chatbot should not appear, even if the page type is enabled.

Example: 5, 30, 200

How to find a page or post ID:

1. Go to Pages (or Posts) in the WordPress admin
2. Hover over the page/post you want
3. Look at the URL in your browser’s status bar — the ID is the number after post=
4. Alternatively, click Edit and check the URL, which shows post.php?post=XX

Page Exclusion (Dropdown)

A user-friendly alternative to ID-based exclusion. Select specific published pages from a dropdown menu to hide the chatbot on those pages, without needing to look up page IDs.

Setting key: excluded_pages

Selected pages appear as tag-like chips with a remove button. Click Add after selecting a page from the dropdown. For posts, use the Exclude IDs field above.

Footer

Controls the “Powered by” footer text displayed at the bottom of the chat widget.

In the Free edition, no footer is shown by default.

The Pro edition allows you to add a custom footer or replace it with your own branding text via Pro Settings > CUSTOMER > Footer & CSS.

Cross-Site Embed

Display your chatbot on external websites that are not running this plugin. Two embed methods are provided with ready-to-use code snippets.

Script Embed (Recommended):

Paste the generated <script> tag before the closing </body> tag on the external site. This creates a floating chat badge identical to the one on your WordPress site.

<script src="https://example.com/wp-content/plugins/rapls-ai-chatbot/assets/js/embed.js"
  data-site="https://example.com"
  data-color="#007bff"
  data-position="bottom-right"
  async></script>

The script loads asynchronously and does not block page rendering. The embed code includes your site URL, primary color, and badge position as data attributes.

Iframe Embed:

Embeds the chat widget directly in the page at a fixed size. The chat window is always visible without requiring users to click a badge. Useful for dedicated support pages.

<iframe src="https://example.com/?wpaic_embed=1"
  width="400" height="600"
  style="border: none; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);">
</iframe>

Both code snippets include a Copy button for easy copying.

add_filter('wpaic_allowed_origins', function($origins) {
    $origins[] = 'external-site.com';
    $origins[] = 'another-site.com';
    return $origins;
});

Security Settings

Configure reCAPTCHA, access control, rate limiting, proxy settings, and view security diagnostics. Navigate to AI Chatbot > Settings > Security Settings tab.

Enable reCAPTCHA v3

Enables invisible Google reCAPTCHA v3 bot protection. reCAPTCHA v3 runs in the background without user interaction and assigns each request a score from 0.0 (likely bot) to 1.0 (likely human).

Setting key: recaptcha_enabled

Enabled: Each chat message is verified with reCAPTCHA before being sent to the AI. Requests scoring below the threshold are blocked.

Disabled: No reCAPTCHA verification. The chatbot relies on other security measures (rate limiting, bot detection).

Default: Disabled

How to set up Google reCAPTCHA v3:

1. Go to https://www.google.com/recaptcha/admin
2. Sign in with your Google account
3. Click the + (Create) button
4. Enter a label (e.g., “My WordPress Site”)
5. Select Score based (v3) as the reCAPTCHA type
6. Add your domain(s) under “Domains” (e.g., example.com)
7. Accept the terms and click Submit
8. Copy the Site Key and Secret Key displayed on the next page
9. Paste both keys into the plugin settings

Site Key / Secret Key

Site Key (recaptcha_site_key):

The public key embedded in the frontend JavaScript. Not a secret; visible in page source. Enter as plain text.

Secret Key (recaptcha_secret_key):

The private key used for server-side verification. Stored encrypted in the WordPress database. After saving, the field shows masked dots. Leave the field empty when saving to keep the current key.

Score Threshold

The minimum reCAPTCHA score required to allow a chat message through.

Setting key: recaptcha_threshold

Default: 0.5 | Range: 0.0 – 1.0 (step 0.1)

Use Existing reCAPTCHA

If another plugin on your site already loads the reCAPTCHA v3 script (e.g., Contact Form 7, WPForms, Gravity Forms), enable this to avoid loading the script twice.

Setting key: recaptcha_use_existing

Enabled: The plugin does not load its own reCAPTCHA script. It reuses the reCAPTCHA instance already available on the page.

Disabled: The plugin loads its own reCAPTCHA v3 script using your Site Key.

Default: Disabled

WP Consent API Strict Mode

Integrates with the WP Consent API for GDPR-compliant behavior regarding localStorage and conversion tracking.

Setting key: consent_strict_mode

Enabled: User ID persistence (localStorage) and conversion tracking are disabled unless a WP Consent API-compatible consent management plugin is active and the user has granted consent. The chatbot itself still works normally — only storage and tracking features are affected.

Disabled: localStorage and conversion tracking work normally regardless of consent status.

Default: Disabled

Rate Limiting

Limits the number of chat messages a single IP address can send within a time window, protecting your API budget from abuse.

Setting keys: rate_limit, rate_limit_window

Max Requests (rate_limit): Maximum messages allowed per IP within the time window. Set to 0 for unlimited.

Default: 20 requests

Time Window (rate_limit_window):

Proxy Settings

Configure how the plugin detects the real visitor IP address when your site is behind a CDN or reverse proxy. Correct IP detection is essential for rate limiting and bot detection.

Trust Cloudflare CF-Connecting-IP (trust_cloudflare_ip):

Enabled: Uses Cloudflare’s CF-Connecting-IP header to detect the real visitor IP. Enable only if your site is behind Cloudflare.

Disabled: Ignores the CF-Connecting-IP header.

Default: Disabled

Trust X-Forwarded-For (trust_proxy_ip):

Enabled: Uses the first public IP from the X-Forwarded-For header. Enable if your site is behind a reverse proxy (Nginx, AWS ALB, etc.).

Disabled: Ignores the X-Forwarded-For header. Uses REMOTE_ADDR directly.

Default: Disabled

Setup examples:

Cloudflare setup:

1. Verify your site is proxied through Cloudflare (orange cloud icon in DNS settings)
2. Enable “Trust Cloudflare CF-Connecting-IP” in plugin settings
3. Save and verify in Security Diagnostics that client IPs are detected correctly

Nginx reverse proxy setup:

1. Ensure your Nginx configuration passes the real IP via X-Forwarded-For:

location / {
    proxy_pass http://backend;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Real-IP $remote_addr;
}

2. Enable “Trust X-Forwarded-For” in plugin settings
3. Add your proxy IP to the trusted proxies list via the filter:

add_filter('wpaic_trusted_proxies', function($proxies) {
    $proxies[] = '10.0.0.1';        // Single IP
    $proxies[] = '172.16.0.0/12';   // CIDR range
    return $proxies;
});

reCAPTCHA Fail Mode

Behavior when reCAPTCHA verification itself fails (e.g., Google’s servers are unreachable, network error).

Setting key: recaptcha_fail_mode

Security Diagnostics

A read-only section at the bottom of the Security Settings tab showing the current security configuration status. All fields are informational and cannot be edited.

Recent Bot Detections (past hour):

Displays requests blocked by the built-in bot detection system. Detection methods include:

• Honeypot: Hidden form fields that bots fill in but real users never see
• Timing: Requests submitted too quickly (faster than human typing speed)
• Future clock: Requests with timestamps in the future (clock manipulation)

Counts marked “(approx)” are sampled 1-in-10 and displayed as estimated totals (x10). Detections are categorized by form type: Offline message, Chat, and Lead capture.

XFF Truncated (past hour): Number of oversized X-Forwarded-For headers truncated. High numbers may indicate a CDN/proxy chain issue or an attack.

Data Management

Configure conversation history storage, data retention, and settings import/export. Navigate to AI Chatbot > Settings > Data Management tab.

Save Conversation History

Controls whether chat conversations are stored in the WordPress database.

Setting key: save_history

Enabled: All conversations and messages are saved to the database. Enables conversation history viewing, analytics, feedback features, and session persistence across page loads.

Disabled: Conversations are processed in memory only and not persisted. Users cannot resume previous conversations, and no analytics data is collected.

Default: Enabled

Retention Period

The number of days to keep conversation history before automatic deletion. A WordPress cron job (wpaic_cleanup_old_conversations) periodically cleans up conversations older than this threshold.

Setting key: retention_days

Default: 90 days | Set to 0 for unlimited retention (conversations are never automatically deleted)

Delete Data on Uninstall

Controls whether plugin data is permanently removed when the plugin is uninstalled (deleted) from WordPress.

Setting key: delete_data_on_uninstall

Enabled: All plugin data is permanently deleted on uninstall, including:

• All database tables (conversations, messages, knowledge base, index, leads)
• All plugin settings and options (wpaic_settings, wpaic_version, etc.)
• Diagnostic data and transients
• Scheduled cron jobs

Disabled: Plugin settings are removed, but database tables (conversations, knowledge base, leads) are preserved for potential reinstallation.

Default: Disabled

Settings Export

Export your plugin settings as a JSON file for backup or migration to another site.

How to export:

1. Navigate to Settings > Data Management
2. Optionally check Include Knowledge Base to export knowledge base entries along with settings
3. Click Export Settings
4. A JSON file will be downloaded to your computer (filename: wpaic-settings-YYYY-MM-DD.json)

What is exported:

• All plugin settings (AI provider, model, chat settings, display settings, security settings)
• Knowledge base entries (if the checkbox is checked)
• Pro feature settings (if Pro is active)

What is NOT exported:

• API keys (for security — you must re-enter them on the target site)
• Conversation history
• Lead data
• Site learning index

Settings Import

Import settings from a previously exported JSON file.

How to import:

1. Navigate to Settings > Data Management
2. Click Choose File and select the exported JSON file
3. Click Import Settings
4. A confirmation message appears listing the settings that will be imported
5. Confirm to apply the imported settings

Settings Reset

Reset all plugin settings to their factory defaults. This does not delete conversation history, knowledge base entries, or other stored data — only the settings are reset.

How to reset:

1. Navigate to Settings > Data Management
2. Click Reset All Settings
3. A confirmation dialog appears asking you to confirm the action
4. Confirm to reset all settings to defaults

Knowledge Base

The Knowledge Base allows you to provide specific Q&A pairs that the chatbot prioritizes over its general AI knowledge. Navigate to AI Chatbot > Knowledge.

Overview

The Knowledge Base is a collection of question-answer pairs you create manually. When a user asks a question that matches (or closely matches) a knowledge base entry, the AI is instructed to use that specific answer rather than generating one from its general training data.

This is the most effective way to ensure accurate, consistent answers for frequently asked questions about your products, services, policies, or any topic specific to your business.

How matching works:

1. Exact Match: If the user’s question exactly matches a knowledge base question, the corresponding answer is used with strict instructions (see Knowledge Exact Match context prompt). The AI will not add external information.
2. Similar Match: If similar questions are found (via keyword or vector search), they are provided as a FAQ database for the AI to reference (see Knowledge Q&A context prompt). The AI may combine information from multiple entries.
3. No Match: If no relevant entries are found, the AI responds using its general knowledge and any site learning context available.

Adding Q&A Entries

Add question-answer pairs using the form at the top of the Knowledge page.

How to add an entry:

1. Navigate to AI Chatbot > Knowledge
2. Fill in the Title (question) field
3. Fill in the Content (answer) field
4. Optionally set a Category and Priority
5. Click Add Knowledge

Entries can be edited and deleted directly from the list. Changes take effect immediately for new conversations.

Entry Fields

File Import

Bulk import knowledge base entries from files. Supported file formats:

How to import:

1. Navigate to AI Chatbot > Knowledge
2. In the File Import section, click Choose File
3. Select your file
4. Optionally select a Category to assign to all imported entries
5. Click Import

CSV Import Format

The CSV file should have columns for question, answer, and optionally category. The first row should be column headers.

Basic format (2 columns):

question,answer
"What are your prices?","Plans start at $10/month. See our pricing page for details."
"What are your business hours?","Monday to Friday, 9 AM to 6 PM EST."

Full format (3 columns):

question,answer,category
"What are your prices?","Plans start at $10/month.","Pricing"
"Do you offer a free trial?","Yes, we offer a 14-day free trial.","Pricing"
"How do I reset my password?","Go to the login page and click Forgot Password.","Account"
"What is your refund policy?","Full refund within 30 days of purchase.","Billing"
"Do you ship internationally?","Yes, we ship to over 50 countries.","Shipping"

Statistics Cards

Four summary cards at the top of the Knowledge page show:

Entry List

Below the statistics cards and add/import forms, the Knowledge page displays a table of all entries with the following features:

• Status Filter: Filter by All / Published / Draft status tabs
• Table Columns: ID, Title, Category, Type, Priority, Updated Date, Actions (Edit/Delete)
• Inline Editing: Click an entry to edit it directly in the list
• Sorting: Click column headers to sort by that column

Free Edition

The Free edition has no artificial limits on the number of knowledge base entries. Add as many Q&A pairs as your site requires.

The Pro edition adds advanced features on top of unlimited entries, such as:

• Draft status for entries under review
• Knowledge versioning and change history
• Auto-priority based on usage frequency
• Expiration dates for time-sensitive content
• Related links between entries
• Intent classification
• AI-powered FAQ auto-generation from knowledge gaps
• Similar question merge detection

Site Learning (Crawler) PRO

Site Learning automatically crawls your WordPress content and makes it available as context for the AI chatbot. Navigate to AI Chatbot > Site Learning.

Overview

The crawler reads your WordPress posts, pages, and custom post types, splits the content into chunks, and stores them in the wp_aichat_index database table with FULLTEXT indexing. When a user asks a question, the plugin searches this index for relevant content and provides it as context to the AI.

This enables the chatbot to answer questions about your site’s content (blog posts, product pages, documentation, etc.) without requiring manual knowledge base entries for each topic.

Status Panel PRO

When Pro is active, the Site Learning page shows a status panel with:

Enable Crawler PRO

Enables or disables the automatic content crawler.

Enabled: Periodically crawls specified post types, splits content into chunks, and stores in the search index. Relevant content is automatically included in AI responses as context.

Disabled: No crawling. The chatbot uses only the manually registered knowledge base entries.

Default: Enabled

Post Types PRO

Which WordPress post types to crawl and index.

Default: All — Crawls all public post types (posts, pages, custom post types including WooCommerce products).

You can select specific types to limit the scope of crawling. Options include posts, pages, and any registered custom post types.

Additional crawl settings available in Pro:

• Excluded Content: Specific pages or posts to skip during crawling
• Custom Fields: Include custom field data in the crawl
• Crawl Depth: How deep to crawl linked content

Crawl Interval PRO

How often the crawler runs automatically via WordPress cron.

A manual crawl button is also available on the Site Learning page for immediate indexing. The Pro edition also supports differential crawling (only new/changed content) and scheduled crawls at specific times.

Chunk Size PRO

Maximum characters per content chunk when splitting crawled content.

Default: 1000 characters

Max Results PRO

Maximum number of content chunks included in the AI context per user query.

Default: 3

Conversations PRO

View and manage chat conversation history. Navigate to AI Chatbot > Conversations.

Overview

The Conversations page provides a comprehensive view of all chat sessions between visitors and the AI chatbot. You can search, filter, export, and review individual conversations to understand user needs and improve the chatbot’s effectiveness.

Statistics Cards PRO

Six summary cards at the top of the Conversations page:

Conversation List PRO

The main table shows all conversations with:

• Search and Filter: Search by message content, filter by status, and date range
• Bulk Operations: Select and delete multiple conversations, reset all sessions
• Table Columns: ID, Session ID, Message Count, Lead info, Start Page, Status, Handoff status, Start Time, Last Update, Actions
• Pagination: Navigate through large conversation lists

Message View PRO

Click a conversation to view the full chronological exchange between user and AI. Features include:

• Full message history with timestamps
• Feedback ratings (thumbs up/down) displayed alongside messages
• User information (session details, browser, IP)
• Conversation summary generation
• Conversation tagging for organization

Export PRO

Export conversation data in CSV or JSON format with optional date range filtering. Useful for external analysis, compliance records, or backup.

Analytics PRO

Comprehensive analytics dashboard for understanding chatbot performance and user engagement. Navigate to AI Chatbot > Analytics.

Overview

The Analytics page provides detailed insights into how visitors interact with your chatbot. In the Free edition, this page shows a preview with sample data to demonstrate the available metrics. Full functionality requires the Pro edition.

Features PRO

The Pro analytics dashboard includes:

Time Period Selection: View data for the last 7, 30, or 90 days. Print or export as PDF.

Statistics Cards:

• Total conversations and messages
• Average messages per conversation
• User satisfaction score (from feedback)
• Estimated API cost for the period
• AI quality score
• Bounce rate (single-message conversations)

Charts and Graphs:

• Conversation dropout distribution (where users leave)
• Daily conversation volume (line chart)
• Hourly distribution (when users are most active)
• Daily cost trends
• Model-wise cost breakdown
• Feedback trends over time

Tables and Reports:

• Most frequently asked questions
• Top pages where chatbot is used
• Device statistics (desktop, mobile, tablet)
• Country-wise usage statistics
• Feedback analysis with satisfaction breakdown
• Knowledge gaps (questions the chatbot could not answer)
• Low-rated feedback entries for improvement

Leads PRO

View and manage lead capture form submissions collected through the chatbot. Navigate to AI Chatbot > Leads.

Overview

The Leads page displays all contact information collected through the chatbot’s lead capture form. Lead capture is a Pro feature that allows you to collect visitor details (name, email, phone, company, custom fields) before or during a chat conversation.

Features PRO

• Search and Filter: Search by name, email, or company. Filter by date range
• Statistics Cards: Total leads, today’s leads, this week, this month
• Lead Table: Name, Email, Phone, Company, Type (lead/offline), Conversation link, Date, Actions
• Export: CSV and JSON export with date range filtering
• Conversation Link: Each lead links to the associated conversation for full context
• Webhook Integration: Automatically send lead data to external CRMs via webhook
• Email Notifications: Receive email alerts when new leads are captured
• Custom Fields: Capture additional custom information specific to your needs

Audit Log PRO

Track and review administrative actions taken within the plugin. Navigate to AI Chatbot > Audit Log.

Overview

The Audit Log records all significant administrative actions performed within the plugin, providing an accountability trail for multi-user WordPress installations.

Features PRO

• Filter by Action Type: Filter logs by action categories (settings change, knowledge edit, data export, etc.)
• Date Range Filter: View logs for specific time periods
• Search: Search log entries by keyword
• CSV Export: Export filtered logs as CSV for compliance or review
• Log Entry Details: Each entry shows the date/time, action type (color-coded by severity), user who performed the action, target object, and details of the change
• Retention Policy: Configure how long audit logs are retained
• Severity Levels: Actions are categorized by severity (informational, warning, critical) with visual color coding

Developer Reference

The plugin provides WordPress filters and a REST API for developers to customize behavior programmatically.

WordPress Filters

Use these filters in your theme’s functions.php or a custom plugin to modify plugin behavior.

Filter Usage Examples:

Add a disclaimer to all AI responses:

add_filter('wpaic_ai_response', function($response) {
    return $response . "\n\n---\n*This is an AI-generated response. For official information, please contact our support team.*";
});

Hide chatbot on WooCommerce checkout pages:

add_filter('wpaic_chatbot_enabled', function($enabled) {
    if (function_exists('is_checkout') && is_checkout()) {
        return false;
    }
    return $enabled;
});

Add context from a custom source:

add_filter('wpaic_context', function($context) {
    // Add custom business data to the AI context
    $hours = get_option('business_hours');
    if ($hours) {
        $context .= "\n\nBusiness Hours: " . $hours;
    }
    return $context;
});

Allow Editors to manage the chatbot:

add_filter('wpaic_manage_cap', function($cap) {
    return 'edit_posts'; // Editors and above can manage
});

Allow cross-site embedding from specific domains:

add_filter('wpaic_allowed_origins', function($origins) {
    $origins[] = 'partner-site.com';
    $origins[] = 'marketing.example.com';
    return $origins;
});

REST API Endpoints

The plugin exposes a REST API under the wp-ai-chatbot/v1 namespace. All endpoints require a valid WordPress nonce for authentication (automatically included when using the chat widget).

Pro-only Additional Endpoints:

Example: Sending a chat message via cURL:

curl -X POST "https://example.com/wp-json/wp-ai-chatbot/v1/chat" \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -d '{
    "message": "What are your business hours?",
    "session_id": "abc123"
  }'

Database Tables

The plugin creates the following tables (prefixed with your WordPress table prefix + aichat_):

Pro-only Tables:

Tables are created by the plugin activator on activation. The Pro plugin uses the same tables (shared database) and does not create its own tables — Pro-specific tables are auto-created when the feature is first used.