=== CrossMediaBot ===
Contributors: ginoize
Tags: chatbot, ai chatbot, ai assistant, customer support, faq bot
Requires at least: 7.0
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 3.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI Business Assistant for WordPress. Answers visitor questions using your knowledge base and site content, powered by the AI provider of your choice.

== Description ==

CrossMediaBot turns your knowledge base and website content into a 24/7 AI assistant. It uses the WordPress AI Client built into WordPress 7.0, so you configure an AI provider once under Settings → Connectors and the chatbot uses it — no separate API key handling inside the plugin. You pay your chosen AI provider directly for what you use, typically a few dollars a month for a small business site.

The bot only answers using content you control: text you write in the knowledge base, and pages indexed by the built-in site crawler. It does not browse the internet and will not fabricate information about your business.

**Features**

* **Knowledge base** — write a description of your business, services, prices, hours, and FAQs in plain text. The bot uses this as its primary source of truth.
* **Site crawler** — crawl up to 200 pages of your WordPress site and index their content automatically. Combined with the knowledge base, the bot can answer questions about any page on your site.
* **Conversation memory** — multi-turn history is sent to the AI on every message, so visitors can ask follow-up questions naturally without repeating themselves.
* **Welcome message** — configure a greeting that appears as the bot's first message when the chat opens.
* **WhatsApp escalation** — hand a conversation over to a human on WhatsApp, with the transcript pre-filled.
* **Full color theming** — 8 independently configurable colors (header background, header text, user bubble, bot bubble, send button, text, links, and background) with a live preview panel, plus automatic theme-color detection.
* **Testing mode** — the chat widget is hidden from all visitors and visible only to logged-in administrators, so you can test privately before going live.
* **Provider and model selection** — choose which configured AI provider and which preferred model the bot should use.
* **Usage statistics** — input, output, and thinking token counts with a per-provider/model breakdown, and the number of conversations logged. Costs are billed directly by your AI provider according to their pricing.
* **Security** — per-IP rate limiting, message length caps, output sanitization, and whitelisted internal links only.

Additional features are offered in a separate plugin, CrossMediaBot Pro, available from [crossmedia297.com](https://www.crossmedia297.com/crossmediabot).


== Installation ==

1. Upload the `crossmedia-chatbot` folder to `/wp-content/plugins/`, or install the ZIP via **Plugins → Add New → Upload Plugin**.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Go to **CrossMediaBot** in the admin sidebar.
4. Set up an AI provider under **Settings → Connectors** (WordPress 7.0). Install one of the official provider plugins (Google, Anthropic, or OpenAI) and enter its credentials there. The chatbot uses whatever provider you configure.
5. Fill in the **Knowledge Base** field with a description of your business — services, prices, hours, FAQs, and any other information visitors are likely to ask about.
6. Optionally go to the **Crawling** tab and click **Start Full Crawl** to index up to 200 pages of your site.
7. Use **Testing Mode** on the General tab to test the widget privately — it is visible only to logged-in administrators until you disable it.
8. Disable Testing Mode when you are ready to go live. The chat widget appears in the bottom-right corner of every page on your site.

== Usage ==

The chat widget is injected automatically via `wp_footer` on every front-end page. No shortcode or page template change is required.

On the **General** tab you can optionally select a specific AI provider and preferred model, or leave both on automatic to let WordPress choose from your configured providers.

== Frequently Asked Questions ==

= Do I need to configure an AI provider? =
Yes. This plugin uses the WordPress AI Client, so a site administrator sets up an AI provider once under Settings → Connectors (for example Google, Anthropic, or OpenAI, each available as an official provider plugin). WordPress manages the provider credentials; the plugin never handles them. Provider free tiers typically cover testing and low-volume use, and production usage is billed by the provider directly.

= How much does it cost to run? =
Costs depend on the AI provider you configure and their pricing, and are billed to you directly by that provider. The plugin's General and About tabs show token usage per provider and model so you can monitor consumption.

= What does the bot actually know? =
Only what you put in the knowledge base and what it finds by crawling your site. The bot does not browse the internet or answer questions about topics outside your content. This means no hallucinations about your business — if you have not told it something, it will say so.

= Does CrossMediaBot see my conversations? =
No. Messages are sent from your WordPress server to your configured AI provider through the WordPress AI Client. Crossmedia297 never receives your conversations, your provider credentials, your knowledge base content, or any visitor data.

= How does the plugin connect to an AI provider? =
This plugin uses the WordPress AI Client built into WordPress 7.0. The site administrator configures an AI provider (such as Google, Anthropic, or OpenAI) once under Settings → Connectors, and WordPress manages the provider connection and API key. The plugin never stores or handles API keys itself. You can optionally choose a specific provider and preferred model on the plugin's General settings tab.

= Are there other versions of this plugin? =
Additional features are offered in a separate plugin, CrossMediaBot Pro, available from https://www.crossmedia297.com/crossmediabot. This plugin is complete and fully functional on its own.

= Does the widget work with any WordPress theme? =
Yes. The widget is injected via `wp_footer` and is self-contained with its own CSS. The Design tab includes a **Detect Theme Colors** button that extracts your theme's primary colors and maps them to the widget automatically.

= Does it work on multisite? =
The plugin has not been tested on multisite networks. Single-site installs are fully supported.

== Security ==

Security was a design priority throughout development.

* **Nonces on every form and AJAX action** — all admin forms and AJAX handlers verify a WordPress nonce before executing. This provides CSRF protection for every privileged operation.
* **Capability checks** — every AJAX handler verifies `current_user_can( 'manage_options' )` before running. The public chat endpoint is intentionally unauthenticated but rate-limited.
* **Rate limiting** — the public chat endpoint allows a maximum of 15 requests per 60 seconds per real client IP, using a TOCTOU-safe transient lock. Shared proxy headers (`X-Forwarded-For`, `CF-Connecting-IP`) are read only when the real `REMOTE_ADDR` is a known private range.
* **Input validation and sanitisation** — the visitor's message is capped at 500 characters and sanitised via `sanitize_text_field`. Conversation history is validated to a maximum of 12 turns with alternating user/model roles, a 32 KB raw JSON cap before decoding, and each turn capped to 1,000 characters.
* **Model ID allowlist** — the model name passes through a strict regex before being used in the API URL, preventing path traversal via a crafted model string.
* **Output escaping** — all PHP output uses `esc_html()`, `esc_attr()`, `esc_url()`, or `wp_kses_post()`. Bot reply links are whitelisted against the indexed URL set. The chat widget renders user messages via jQuery `.text()`, not `.html()`, so user-supplied content can never inject markup.
* **Prompt injection mitigation** — the knowledge base is wrapped in delimiters inside the AI `systemInstruction` field, making it harder for a visitor to override system behavior through message content.
* **Credential handling** — the plugin does not store or transmit AI provider API keys. All provider credentials are managed by WordPress core's Connectors infrastructure, not by this plugin.
* **Database** — all direct database queries use `$wpdb->prepare()`. All output is escaped at the point of rendering.

== External services ==

This plugin generates chatbot replies through the WordPress AI Client that is built into WordPress 7.0. The plugin itself does not connect to any third-party API directly and does not store or transmit AI provider API keys. Instead, it hands the prompt to WordPress core, which sends it to whichever AI provider you have configured under Settings → Connectors (for example Google, Anthropic, or OpenAI). The specific external service that receives the data is therefore the provider you choose; the plugin has no built-in or default provider of its own.

**What data is sent, and when:** each time a visitor sends a message to the chatbot, the plugin passes the visitor's message, the recent conversation history for that session, and your configured knowledge base text (and, if site crawling is enabled, text extracted from your selected pages) to WordPress core's AI Client, which forwards it to your configured AI provider so a relevant reply can be generated. No data is sent until a visitor actually interacts with the chatbot, and no data is sent to Crossmedia297.

**Where it goes:** to the AI provider you configured under Settings → Connectors. That provider's own terms of service and privacy policy govern how it handles the data, so please review them before enabling the chatbot. The providers most commonly used with the WordPress AI Client are:

* Google (Gemini API) — Terms: https://ai.google.dev/gemini-api/terms — Privacy: https://policies.google.com/privacy
* Anthropic (Claude) — Terms: https://www.anthropic.com/legal/commercial-terms — Privacy: https://www.anthropic.com/legal/privacy
* OpenAI — Terms: https://openai.com/policies/terms-of-use — Privacy: https://openai.com/policies/privacy-policy

If you configure a provider other than these, consult that provider's own terms and privacy policy. This plugin has no default provider and sends nothing anywhere until you configure one.

This plugin also makes requests to your own website (same domain) when you use the site crawler to index your pages, and, if your theme's own files do not provide enough colour information, when the "Detect theme colors" tool reads your homepage. These are requests to your own server, not to a third-party service.

== Screenshots ==

1. The chat widget on the front end of the site.
2. General settings: choosing the AI provider and preferred model, the knowledge base, and the welcome message.
3. The Design tab: widget colours with live preview and automatic theme-colour detection.
4. The Crawling tab: indexing site content for the bot to reference.
5. Usage statistics: token counts per provider and model.

== Changelog ==

= 3.2.0 =
* First public release on WordPress.org.

== Upgrade Notice ==

= 3.2.0 =
First public release on WordPress.org.
