XC Chatbot

A premium white-label AI chat widget for WordPress, with multi-provider AI, a local website-only knowledge base, secure attachments, optional image and PDF analysis, and a domain-pack system to specialise the bot per industry. This document covers configuration, behaviour, the REST surface, and operational concerns.

Introduction ¶

XC Chatbot adds a floating chat widget to any WordPress front-end. Conversations are routed through either Anthropic Claude or OpenAI GPT, with first-class streaming, server-side enforcement of website-only answers, and a private attachment pipeline. The plugin is designed to be operable without code changes — every behaviour described below is reachable from the admin UI.

This documentation is split into five parts:

• Getting started — install, requirements, first run.
• Configuration — every admin page, field by field.
• Behaviour — what happens when a message is sent, how the bot decides what to say, and where the limits sit.
• Reference — REST API, AJAX endpoints, hooks, schemas, options.
• Operations — troubleshooting, performance, uninstall.

Requirements ¶

Installation ¶

1. Upload the plugin folder xc-chatbot/ to wp-content/plugins/ (or upload the .zip via Plugins → Add New → Upload).
2. Activate the plugin from the Plugins screen. On activation, two tables are created and the initial KB reindex is scheduled for ~60 seconds later.
3. Open AI Chatbot in the admin sidebar. The configuration is split across eight sub-pages.

What happens on activation

• A non-destructive merge of default settings is written to wp_options under xc_chatbot_settings. Existing values are preserved on re-activation.
• Two tables are created via dbDelta:
  • {prefix}xc_chatbot_kb_docs — local knowledge base
  • {prefix}xc_chatbot_chat_files — attachment registry
• Three cron events are scheduled: an hourly attachment cleanup, a one-shot initial KB reindex, and a daily/weekly KB reindex (configurable).
• A private upload directory is prepared on first upload at wp-content/uploads/xc-chatbot-private/, with a deny-all .htaccess and an empty index.php.

What happens on deactivation

All scheduled cron events registered by the plugin are cleared. Tables, options, and the private upload directory are not removed — see Uninstall for full removal.

First run ¶

The minimum to reach a working chat:

1. Open AI Chatbot → AI & API.
2. Choose a provider (Anthropic recommended; OpenAI required for image / PDF analysis).
3. Paste an API key. It is encrypted at rest before the option is written.
4. Click 🔌 Test. A 200 from the upstream means the key is valid; HTTP code mappings are surfaced as short hints — the plugin never echoes upstream error.type codes.
5. Save the page. Open the front-end — the chat widget appears in the configured corner.

By default the bot is restricted to your website content (Knowledge Base → Restrict to indexed website content). On a fresh install the KB is empty until the initial reindex runs, so the bot will politely apologise and direct visitors to the contact buttons. To start answering immediately, click 🔄 Reindex on the Knowledge Base page or disable site-only mode while content is being indexed.

Admin overview ¶

The plugin adds a top-level menu item with eight sub-pages. Settings are written through page-scoped POST handlers; nonces are scoped per-page (xc_chatbot_save_{page}).

General ¶

Chatbot Identity

Behaviour

White Label

AI & API ¶

Provider & key

The plugin supports two providers, selected by api_provider:

• Anthropic — uses POST https://api.anthropic.com/v1/messages. Streaming uses stream: true with the Server-Sent Events response that Anthropic emits natively.
• OpenAI — uses POST https://api.openai.com/v1/chat/completions with split text / vision model routing (see below).

The API key is encrypted with AES-256-CBC before being stored in wp_options. The cipher key is derived from a SHA-256 of LOGGED_IN_SALT, NONCE_SALT and AUTH_SALT. Stored values are prefixed:

The admin field shows a masked value (sk-a••••••••••••••••••••DEFG). Submitting a form whose API-key field still contains • characters is treated as "no change" and the existing encrypted value is preserved. To rotate a key, clear the field and paste the new value.

Anthropic models

OpenAI models — split routing

OpenAI is configured with two model slots:

• Text model (openai_model_text) — used for plain text conversations.
• Vision model (openai_model_vision) — used only when the request includes image content parts. The plugin inspects the user content and switches automatically.

Routing is decided by XC_Chatbot_Chat_Handler::stream_response() just before the upstream call: if any image_url content part exists or a PDF was rendered to JPEG, the vision slot is used. Otherwise, the text slot is used. This keeps cost low for plain text while still permitting vision for the same conversation.

System prompts

Prompt rules

Each rule has a name, a type (default, translation, or technical), a comma-separated keywords list, and a prompt. Rules are evaluated top-to-bottom; first keyword match wins. Domain pack rules merge in front of admin rules — pack rules are evaluated first.

Maximum 25 rules are saved (further rows are silently dropped).

Knowledge Base ¶

The KB indexes selected post types into a local FULLTEXT-enabled table and uses it for retrieval-augmented generation. Two policies coexist:

• Site-only mode (kb_site_only=1, default) — replies must be derived from indexed pages or attached files. If neither exists, the bot returns the configured apology in the user's detected language.
• Open mode (kb_site_only=0) — the model may answer from its training knowledge.

Search & Answers

Indexing

Internal-only output policy

External URLs are stripped post-generation by enforce_website_only_output(). The model's reasoning may be open, but the rendered answer cannot leak outside the indexed site.

Action buttons

• 🔄 Reindex — clears the running job, schedules a new one, and runs the first batch synchronously so the status panel updates immediately.
• ⚡ One Batch — runs exactly one batch. Useful when WP-Cron is disabled.
• 🗑️ Clear Index — truncates the KB table and resets state. Confirmation prompt via data-xc-confirm.

Attachments ¶

Attachments are stored privately, outside the WordPress media library, in wp-content/uploads/xc-chatbot-private/YYYY/MM/. Files are served only through the REST download endpoint, which checks both a nonce and per-actor ownership.

File Upload

AI Analysis (OpenAI only)

See Attachment AI for the full extraction pipeline.

Contact Bar ¶

The contact bar is an in-chat row of buttons (Email, Call, named departments, Contact page) that gives visitors a non-AI escape hatch.

Display

Contact details

Reply CTA

An optional one-sentence hint that the bot appends to its replies, telling the user the contact buttons are right below.

Localized strings are built into the chat handler for en, ro, fr, nl, de; other languages fall back to English.

Design ¶

The widget exposes two CSS variables — --xc-chatbot-primary and --xc-chatbot-accent — that drive the gradient on the trigger button, the header, the user bubbles, and the antenna of the avatar SVG.

Both values are validated server-side with sanitize_hex_color() before being persisted.

Domain Packs ¶

A domain pack is a JSON document that overrides system prompt, brand policy, prompt rules, quick replies, contact keywords, and the KB apology in one operation. The pack data is written to wp_options under xc_chatbot_domain_packs (keyed by pack_id); the active pack is recorded in xc_chatbot_settings.domain_pack_active.

Bundled samples

Five samples ship in domain-packs/:

• industrial — error codes, fault diagnosis, maintenance, spare parts.
• medical — appointment-style triage, treatment Q&A. Always recommends consulting a clinician.
• pedagogic — tutoring tone, scaffolded explanations.
• literary — bookshop / publisher tone, recommendations and series.
• sports — league / club tone, tickets and fixtures.

Click a bundled sample to import it. Importing a sample whose pack_id already exists silently overwrites it.

How merging works

1. Base values are read from xc_chatbot_settings.
2. Pack values override base values when present:
   • system_prompt_default — replaces base.
   • brand_policy — replaces base.
   • prompt_rules — pack rules go first, then base rules. Capped at 30 rules total.
   • quick_replies — replaces base if non-empty.
   • contact_keywords_append — appended to existing keywords.
   • kb_policy_apology — replaces base if non-empty.

The merged result is computed at runtime in XC_Chatbot_Domain_Packs::get_effective_config() and is read by the chat handler before each request — no save step is required after activating a pack.

Import / export

• Upload & Import — accepts a single .json file. Validates schema, sanitizes every field, caps rules to 30 and quick replies to 8.
• 📤 Export — serves the active pack JSON as a download (domain-pack-{pack_id}.json), excluding the imported_gmt internal field.
• 🗑️ Remove — deletes a pack (with confirmation). If it was active, deactivates it.

For the JSON shape, see Domain pack schema.

Diagnostics ¶

A read-only environment audit. Useful before opening a support ticket. Reports:

• WordPress and PHP versions.
• HTTPS status (is_ssl()).
• Whether openssl_encrypt is available (otherwise the plugin uses base64 obfuscation).
• Whether the stored API key is encrypted, plaintext, or unset.
• Private upload directory path, existence, and writability.
• GD and Imagick availability.
• upload_max_filesize and post_max_size from the active PHP config.

Prompt routing ¶

For every user message, the chat handler decides which system prompt to use:

1. Read effective config (base + active domain pack).
2. If use_advanced_rules=1, evaluate prompt_rules top-to-bottom. The first rule whose comma-separated keywords contain a substring of the user message wins. Its type drives downstream behaviour (translation bypasses the brand policy and the website-only KB injection).
3. If no rule matches, fall back to a hard-coded translation/technical pair derived from system_prompt_translation + prompt_keywords_translation and system_prompt_technical + prompt_keywords_technical.
4. If still no match, use system_prompt_default.
5. Append brand_policy unless the intent is translation.
6. Append a LANGUAGE: … instruction (see Language detection).
7. If site-only mode is on, append the website-only policy and the retrieved KB context block.
8. If attached files are present and Attachment AI is allowed for this actor, append the attachment policy block.

Language detection ¶

Three modes (answer_language_mode):

The detected language is used in three places:

• The LANGUAGE: instruction appended to the system prompt.
• Localization of the rate-limit and stream-busy messages.
• Localization of the KB apology when the admin left the apology at the English default.

KB retrieval ¶

Retrieval runs in three tiers, each falling back to the next on no results:

1. FULLTEXT NATURAL LANGUAGE MODE — primary. Score is the MySQL relevance score.
2. FULLTEXT BOOLEAN MODE with simple token expansion (+token*). Stop-words are removed and tokens shorter than 3 characters are dropped.
3. LIKE on title and content with esc_like(). Always available; assigns score 1.

Before retrieval, if the current page URL maps to a post (url_to_postid), that document is included with a synthetic high score so the bot is biased toward the page the user is viewing. Results are de-duplicated by URL and capped at kb_retrieve_limit.

Context block format

Documents are formatted into a single textual block with numeric markers used by the citation system:

[1] Title — https://example.com/page-a
Excerpt body…

[2] Title — https://example.com/page-b
Excerpt body…

The model is asked to cite as [1], [2]… If kb_citations_mode=auto and the model forgets, the response post-processor inserts a basic citation per paragraph.

Streaming & rate limits ¶

The streaming endpoint emits Server-Sent Events. A typical session looks like:

: xc-chatbot stream start

data: {"token":"Hello"}

data: {"token":" — how"}

data: {"token":" can I help?"}

data: [DONE]

Errors are emitted as a single data: {"error":"…"} followed by [DONE].

Rate limits (per actor)

Best-effort, transient-backed limits enforced inside enforce_stream_rate_limits(). The fingerprint is md5(IP|sid|user_id); IP is sanitized through a strict character filter before use to defeat header spoofing.

Rate-limit and stream-busy messages are localized to en/ro/fr/nl; other languages fall back to English. The lock is released by a register_shutdown_function() safety net even if the script is interrupted mid-stream.

Server-side caps

Excess content is silently truncated. Roles in client-supplied history are whitelisted to user or assistant — no role injection is possible.

Attachment AI ¶

Optional. Off by default. Activates only when:

• attachments_ai_enabled=1.
• The current actor is allowed (attachments_ai_allow_users for logged-in, attachments_ai_allow_guests for guests).
• The selected provider is OpenAI.
• The intent is not translation.

Image pipeline

1. The file MIME is verified to start with image/.
2. If the file is ≤ ~4 MB, original bytes are base64-encoded into a data: URL and passed as an image_url content part.
3. If larger, the plugin attempts a GD downscale to JPEG. If GD is unavailable, the image is dropped and a note is emitted to the model.
4. Up to attachments_ai_max_images images per message; the rest are skipped with a note.

PDF pipeline

1. Text path: if pdftotext is on PATH (or at /usr/bin/pdftotext, /usr/local/bin/pdftotext, /bin/pdftotext), it is invoked with -f 1 -l N -layout to extract the first N = attachments_ai_pdf_pages pages. Output is normalized and length-capped at attachments_ai_max_chars.
2. Vision fallback: if no text is recoverable, the first page is rendered to JPEG using pdftoppm first (-f 1 -l 1 -singlefile -jpeg -r 150). If pdftoppm is missing, Imagick is tried (readImage($pdf.'[0]') at 150 DPI). The JPEG is then handed to the vision model just like any other image.
3. If neither path produces content, a note like Could not extract text or render PDF: invoice.pdf is added to the system context — the model is told what was attached but warned not to hallucinate the content.

All shell invocations use escapeshellarg() on every argument. The chosen binary is selected from a fixed candidate list, never from user input.

Fallback / demo mode ¶

If no API key is configured, the chat handler enters a deterministic demo mode that simulates streaming over a small, hard-coded response table. This is intentional — it gives an admin who installs the plugin without an API key something tangible to look at, and it gracefully degrades instead of failing visibly to visitors.

If the website-only policy is on and the KB returns nothing, the bot returns the apology even in demo mode — there is no risk of fabricated answers leaking when the key is missing.

REST API ¶

All endpoints are under the xc-chatbot/v1 namespace. Authentication is performed inside each callback by verifying a per-action nonce; this allows guest sessions to authenticate via the xc_chatbot_sid HttpOnly cookie without losing the protection of wp_verify_nonce().

AJAX endpoints ¶

Two legacy admin-ajax.php actions are registered:

Hooks & cron ¶

Cron events

WordPress action / filter integration

Database tables ¶

{prefix}xc_chatbot_kb_docs

CREATE TABLE {prefix}xc_chatbot_kb_docs (
  id             BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
  post_id        BIGINT(20) UNSIGNED NOT NULL,
  post_type      VARCHAR(40)  NOT NULL DEFAULT '',
  title          TEXT         NOT NULL,
  url            TEXT         NOT NULL,
  excerpt        TEXT         NOT NULL,
  content        LONGTEXT     NOT NULL,
  image_url      TEXT         NULL,
  images_json    LONGTEXT     NULL,
  run_id         BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
  modified_gmt   DATETIME     NULL,
  indexed_gmt    DATETIME     NOT NULL,
  PRIMARY KEY (id),
  UNIQUE KEY post_id (post_id),
  KEY run_id (run_id),
  FULLTEXT KEY ft_title_content (title, content)
);

run_id is a monotonically-increasing identifier set at the start of each full reindex, used by the post-reindex sweep to drop documents that were not touched by the current run.

{prefix}xc_chatbot_chat_files

CREATE TABLE {prefix}xc_chatbot_chat_files (
  id           BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  file_key     VARCHAR(64)   NOT NULL,
  sid          VARCHAR(64)   NOT NULL,
  user_id      BIGINT UNSIGNED NOT NULL DEFAULT 0,
  orig_name    TEXT          NOT NULL,
  stored_path  TEXT          NOT NULL,
  mime         VARCHAR(190)  NOT NULL,
  size         BIGINT UNSIGNED NOT NULL DEFAULT 0,
  created_gmt  DATETIME      NOT NULL,
  used         TINYINT(1)    NOT NULL DEFAULT 0,
  PRIMARY KEY (id),
  UNIQUE KEY file_key (file_key),
  KEY sid (sid),
  KEY user_id (user_id),
  KEY created_gmt (created_gmt)
);

file_key is a 24-character hex value generated from random_bytes(12). It is the only identifier exposed in URLs; the actual filesystem path is never user-visible.

Options reference ¶

All settings live in a single serialized array at wp_options.xc_chatbot_settings. The plugin performs a non-destructive merge of defaults on every read, so newly added keys appear automatically after upgrades without overwriting existing values.

None of these options are autoloaded except the main settings array. Encrypted API keys live inside xc_chatbot_settings with the enc: prefix.

Domain pack schema ¶

{
  "pack_id": "industrial",                   // required, [a-z0-9_-]{1,64}
  "pack_name": "Industrial & Technical",    // optional, defaults to pack_id
  "version": "1.0",
  "description": "Specialised for…",

  "system_prompt_default": "You are…",
  "brand_policy":          "You are the official…",

  "prompt_rules": [
    {
      "name":     "Error Code Diagnosis",
      "type":     "technical",            // default | translation | technical
      "keywords": "error, fault, code",
      "prompt":   "You are a diagnostic assistant…"
    }
  ],                                              // max 30 rules

  "quick_replies": [
    { "icon": "🔧", "label": "Report error", "msg": "…" }
  ],                                              // max 8 items

  "contact_keywords_append": "technician, …",
  "kb_policy_apology":        "Sorry — I can only…"
}

Validation is strict: every string field is sanitized with sanitize_text_field() or sanitize_textarea_field(); type is whitelisted to default, translation, technical; rules with empty prompt are dropped; quick replies with empty label or msg are dropped.

Privacy & storage ¶

Conversations

By default the plugin does not log conversation content. Messages are streamed through the chat handler to the configured AI provider and the response is sent back to the visitor — no per-message database row is written. Aggregate counters (xc_chatbot_total_messages) are not enabled in v1.0.0.

Visitors may invoke the transcript-download or ZIP-export buttons themselves; in both cases the transcript is generated client-side from the in-memory chat log and never persisted on the server.

Cookies

The cookie value is 32 hex characters from random_bytes(16). It contains no user-identifying information.

Attachments

• Stored in wp-content/uploads/xc-chatbot-private/YYYY/MM/.
• The directory contains a deny-all .htaccess and an empty index.php.
• File names on disk are {file_key}.{ext} — original names are preserved only inside the database for display.
• Auto-deleted after attachments_retention_days by the hourly cleanup cron.
• Download is gated by nonce + ownership check.

API key

Encrypted at rest (AES-256-CBC), key material derived from WordPress salts. The plaintext is held in memory only for the duration of an upstream API call. The admin UI displays a masked value and never sends the encrypted blob back to the browser.

File layout ¶

xc-chatbot/
├── xc-chatbot.php                                // main plugin file, bootstrap
├── readme.txt
├── MANIFEST.md
├── admin/
│   └── class-xc-chatbot-admin.php                // admin UI, settings save/dispatch
├── assets/
│   ├── css/xc-chatbot.css                        // front-end widget styles
│   ├── css/xc-chatbot-admin.css                  // admin styles
│   ├── js/xc-chatbot.js                          // front-end widget
│   ├── js/xc-chatbot-admin.js                    // admin JS (delegated handlers)
│   └── images/xc-chatbot-avatar.svg
├── domain-packs/
│   ├── industrial.json
│   ├── medical.json
│   ├── pedagogic.json
│   ├── literary.json
│   └── sports.json
└── includes/
    ├── class-xc-chatbot-settings.php             // options + non-destructive merge
    ├── class-xc-chatbot-crypto.php               // AES-256-CBC for API key
    ├── class-xc-chatbot-domain-packs.php         // pack import/export/merge
    ├── class-xc-chatbot-kb.php                   // KB indexer + retriever
    ├── class-xc-chatbot-attachments.php          // uploads, REST endpoints
    ├── class-xc-chatbot-attachment-ai.php        // image/PDF analysis
    ├── class-xc-chatbot-chat-handler.php         // streaming, prompts, widget render
    └── class-xc-chatbot-assets.php               // enqueue with mtime-busted versions

Troubleshooting ¶

Streaming stops mid-reply / hangs

Almost always a buffering issue upstream of WordPress. Symptoms: chat shows the typing indicator, the request reaches OpenAI / Anthropic, but tokens arrive in one large lump or never arrive. Resolution checklist:

• Verify Cloudflare or other CDN is not in "Buffer entire response" mode for the /wp-json/ path.
• For Apache + mod_pagespeed, exclude /wp-json/xc-chatbot/v1/stream.
• For LiteSpeed cache, add the path to the "Do Not Cache URIs" list.
• For Nginx, ensure proxy_buffering off for the path or globally for SSE.

"Invalid security token"

The widget caches the page nonce. If the page was served from a static / page cache, the embedded nonce can be stale. The widget calls GET /wp-json/xc-chatbot/v1/nonce to refresh on first error; a second occurrence usually means caching is too aggressive — exclude logged-in users or exclude the page from the cache.

"Documents: 0" even after reindex

• Open Knowledge Base, click ⚡ One Batch manually. The status panel updates after the call returns.
• Check the Diagnostics page for table existence.
• Look at kb_post_types — by default it is page + post (+ product if WooCommerce is present). Custom post types must be added explicitly.
• If WP-Cron is disabled (DISABLE_WP_CRON=true), set up an external cron — see CLI & cron.

PDF analysis returns nothing useful

• SSH into the server and run command -v pdftotext pdftoppm. If both are missing, install poppler-utils.
• If you can only run Imagick, check the ImageMagick policy file (/etc/ImageMagick-6/policy.xml or similar) for a PDF read restriction.
• Some PDFs contain only scanned images and no text layer. The plugin will fall back to vision rendering, but only the first page is rendered.

Attachments fail: "File type could not be verified"

This is wp_check_filetype_and_ext() rejecting a file whose real MIME does not match its extension — for example, a renamed .txt file or a PDF saved with the wrong extension. The check is intentional. Re-save the file with the correct extension or extend attachments_allowed_exts if you legitimately need the format.

Performance tuning ¶

Indexing

Inference cost

Front-end

Asset versioning uses filemtime() on every CSS / JS file the plugin enqueues, so cache busting is automatic on edits. The widget is added in wp_footer with defer-equivalent semantics (script in footer); it does not block paint.

CLI & cron ¶

The plugin does not register WP-CLI commands in v1.0.0, but standard cron events can be triggered manually:

# Run any due plugin cron events
wp cron event run --due-now

# Trigger one KB reindex batch
wp cron event run xc_chatbot_kb_reindex_batch

# Force a full reindex from scratch
wp cron event run xc_chatbot_kb_scheduled_reindex

If DISABLE_WP_CRON is set in wp-config.php, schedule a system cron entry:

# /etc/cron.d/wp-xc-chatbot — every minute
* * * * * www-data curl -s https://example.com/wp-cron.php?doing_wp_cron >/dev/null 2>&1

# or with WP-CLI
* * * * * www-data /usr/local/bin/wp --path=/var/www/example cron event run --due-now

Uninstall ¶

Deactivating the plugin clears scheduled cron events but does not remove data. To remove the plugin completely:

1. Deactivate from Plugins.
2. Delete from Plugins (or remove the xc-chatbot/ directory).
3. Drop the two database tables:

   DROP TABLE {prefix}xc_chatbot_kb_docs;
   DROP TABLE {prefix}xc_chatbot_chat_files;

4. Delete the four options:

   DELETE FROM {prefix}options
   WHERE option_name IN (
     'xc_chatbot_settings',
     'xc_chatbot_domain_packs',
     'xc_chatbot_kb_state',
     'xc_chatbot_kb_reindex_job'
   );

5. Remove the private upload directory:

   rm -rf wp-content/uploads/xc-chatbot-private/