Title: ChatHearth – AI Chatbot Author: palwp Published: August 24, 2026 Last modified: August 24, 2026 --- Search plugins ![](https://s.w.org/plugins/geopattern-icon/chathearth.svg) # ChatHearth – AI Chatbot By [palwp](https://profiles.wordpress.org/palwp/) [Download](https://downloads.wordpress.org/plugin/chathearth.1.4.8.zip) * [Details](https://wordpress.org/plugins/chathearth/#description) * [Reviews](https://wordpress.org/plugins/chathearth/#reviews) * [Installation](https://wordpress.org/plugins/chathearth/#installation) * [Development](https://wordpress.org/plugins/chathearth/#developers) [Support](https://wordpress.org/support/plugin/chathearth/) ## Description ChatHearth – AI Chatbot adds a floating chat widget to your site. Visitors get a welcome message and starter phrases, then chat with an AI assistant configured through WordPress Connectors. Owned by [PalWP](https://palwp.com/). Support by [Mohammed Al-Madhoun](https://profiles.wordpress.org/momadhoun/)(` momadhoun`). **Version 1 highlights** * OpenAI via WordPress Connectors / AI Client (provider and chat model selectable in settings) * Settings page under Settings ChatHearth – AI Chatbot (Welcome, Protection, Appearance, AI Settings, Knowledge Base) * Appearance controls (shape, colors, position, popup size) * Welcome message and clickable starter phrases * System prompt settings plus always-on website-only grounding * Knowledge Base (RAG): markdown from selected pages, posts, custom post types, products, and taxonomies; embeddings stored in the WordPress database; incremental updates * Product comparison in chat and add to WooCommerce cart from the widget * The chat icon is not shown on the site until an OpenAI API key is configured under Connectors * Answers questions about the page the visitor is currently viewing (public WordPress content for that URL) * Protection: kill switch, per-IP and site-wide (global) rate limits, escalation email/admin notice, optional auto-disable, max message length, content moderation( keyword list + optional OpenAI Moderations API), optional Google reCAPTCHA v3 overlay (once per hour after first success; enabled when both keys are set) * Conversation history in the browser (localStorage) * Non-streaming replies with a typing indicator and Markdown rendering Configure your OpenAI API key under **Connectors**. This plugin does not store the API key. **Planned: Evaluation and observability** Later releases are expected to add more CAPTCHA providers (Cloudflare Turnstile, hCaptcha), tokens and cost monitoring, hard cost ceilings with admin escalation, latency and reliability metrics, RAG quality evaluation, hallucination detection, explainability, transparency, and controllability. See the plugin `plan/` docs ( especially `metrics-and-methods-for-quality.md` and `functionalities.md`) for details. ### External services This plugin relies on the following third-party services to work. It does not send any data to these services until the site owner configures them and a visitor actively uses the chatbot. No visitor is tracked automatically, and the plugin adds no analytics, advertising, or usage-tracking calls of its own. #### OpenAI (AI chat replies) The chatbot generates replies using OpenAI’s API, accessed through WordPress Connectors/ the core AI Client and the required “AI Provider for OpenAI” plugin. This is the core service that produces the assistant’s answers. * **What is sent:** the text of the message a visitor types, the recent conversation history from that visitor’s browser session, the site’s configured system prompt, the URL and WordPress id of the page they are viewing (so the assistant can load that page’s public content from WordPress — not the raw HTML from the browser), and the selected model name. * **When it is sent:** only when a visitor actively submits a message in the chat widget. Nothing is sent on page load or in the background. * **Where the API key lives:** the OpenAI API key is configured under WordPress Connectors (or the `OPENAI_API_KEY` environment variable / constant). This plugin does not store the API key and does not store chat transcripts in the WordPress database. OpenAI Terms of Use: https://openai.com/policies/terms-of-use/ OpenAI Privacy Policy: https://openai.com/policies/privacy-policy/ OpenAI API data usage policy: https:// openai.com/policies/usage-policies/ #### OpenAI Moderations API (content moderation) When content moderation is enabled under Settings ChatHearth – AI Chatbot Protection and the OpenAI Moderations layer is on, visitor message text is checked with OpenAI’s Moderations endpoint before a chat reply is generated. This helps block harmful or disallowed content and ToS-violating usage. * **What is sent:** the text of the current message and prior user turns from that visitor’s browser session (truncated to a safe length). No system prompt is sent to Moderations. * **When it is sent:** only when a visitor submits a message, content moderation is enabled, the OpenAI Moderations option is on, and OpenAI is configured under Connectors. If moderation is off or only the keyword list is used, this endpoint is not called. * **Where the API key lives:** the same OpenAI API key from WordPress Connectors( or `OPENAI_API_KEY`). This plugin does not store a separate moderation key. * **Endpoint used:** `https://api.openai.com/v1/moderations` OpenAI Terms of Use: https://openai.com/policies/terms-of-use/ OpenAI Privacy Policy: https://openai.com/policies/privacy-policy/ OpenAI API data usage policy: https:// openai.com/policies/usage-policies/ #### OpenAI Embeddings API (knowledge base) When the Knowledge Base (RAG) is enabled, ChatHearth creates embeddings for selected site content and for visitor questions so matching passages can be retrieved. This uses the same OpenAI API key from Connectors. * **What is sent:** markdown generated from selected pages, posts, products, taxonomies, and site/store summaries (at index time), and the visitor’s current question ( at chat time). * **When it is sent:** only when RAG is enabled and the site owner runs a sync / content changes, or a visitor sends a chat message while RAG is on. * **Endpoint used:** `https://api.openai.com/v1/embeddings` Embeddings and generated markdown stay on this WordPress site (custom tables and` uploads/chathearth/kb/`). The plugin does not contact Chroma, Pinecone, or any other vector-database service. #### Google reCAPTCHA v3 (optional bot/abuse protection) Google reCAPTCHA v3 is an optional, score-based human-verification service used only to protect the chat endpoint from automated abuse. It is **disabled by default** and only becomes active when the site owner provides both a reCAPTCHA site key and secret key (under Settings ChatHearth – AI Chatbot Protection, or via the `CHATHEARTH_RECAPTCHA_SITE_KEY` and `CHATHEARTH_RECAPTCHA_SECRET_KEY` environment variables). * **What is sent:** when enabled, the reCAPTCHA JavaScript is loaded from Google on front-end pages where the chat widget appears, and Google may collect device, browser, and usage data (including the visitor’s IP address) to assess whether the visitor is human. When the chat opens, a verification token and the visitor’s IP address are sent to Google’s verification endpoint. A white, translucent, blurred overlay covers the chat window until verification succeeds. * **When it is sent:** only when the site owner has enabled reCAPTCHA (both keys set). If reCAPTCHA is not configured, no request is ever made to Google and Google’s script is not loaded. * **Endpoints used:** `https://www.google.com/recaptcha/api.js` (script) and `https:// www.google.com/recaptcha/api/siteverify` (server-side verification). Google Terms of Service: https://policies.google.com/terms Google Privacy Policy: https://policies.google.com/privacy #### Privacy and consent This plugin does not track users and does not contact any external server without consent: * **OpenAI** is only reached after the site owner installs the required provider plugin and configures an API key under Connectors. By installing, configuring, and activating that service, the site owner grants consent for chat messages to be sent to OpenAI (the Software as a Service exception). Data is sent only when a visitor actively submits a message. When content moderation with OpenAI Moderations is enabled, message text may also be sent to OpenAI’s Moderations endpoint before a reply is generated. * **Google reCAPTCHA** is opt-in and off by default. It loads and contacts Google only after the site owner enters both reCAPTCHA keys. With no keys set, Google is never contacted. * **No silent tracking:** the plugin includes no analytics, advertising, fingerprinting, or usage-tracking calls. The visitor’s IP address is used locally for rate limiting and abuse protection only (short-lived counters), and is not sold, shared, or logged as a chat transcript. Site owners should review the privacy policies of any service they enable and update their own site’s privacy policy accordingly. Suggested privacy-policy text is provided under Settings Privacy. ## Installation 1. Install and activate the **AI Provider for OpenAI** plugin. 2. Add your OpenAI API key under WordPress **Connectors**. 3. Upload the `chathearth` folder to `/wp-content/plugins/`, or install the zip. 4. Activate **ChatHearth – AI Chatbot**. 5. Open **Settings ChatHearth – AI Chatbot** and save your settings. ## FAQ ### Does this plugin store my OpenAI API key? No. Use WordPress Connectors (or the OPENAI_API_KEY environment variable / constant). ### Why don’t replies stream token by token? WordPress AI Client / Connectors do not expose streaming yet. v1 shows a typing indicator, then the full reply. Streaming is planned for a later release. ### Where is chat history stored? In the visitor’s browser via localStorage. Server-side history is planned for a future release. ### How does abuse / rate-limit protection work? Under Settings ChatHearth – AI Chatbot Protection you can set per-IP limits, site- wide (global) limits, an escalation threshold, and optional auto-disable. Optionally add Google reCAPTCHA v3 site and secret keys — CAPTCHA turns on automatically when both are set (green status in settings). Visitors then see a white blurred overlay on the chat window until Google verifies them. Content moderation can check messages with a keyword list and/or OpenAI’s Moderations API before they reach the chat model. Chat requests are checked in order: kill switch, reCAPTCHA (if enabled), then global limits, then per-IP limits, then content moderation (if enabled), then the AI call. When global limits are hit repeatedly within an hour, the plugin emails the admin, shows an admin notice, and can turn the chatbot off automatically. ### Will there be usage, cost, or quality monitoring? Yes — planned under Evaluation and observability (tokens/cost, latency, groundedness, hallucination checks, admin dashboards). Request-count protection, admin escalation, and optional reCAPTCHA v3 ship now; hard dollar/token ceilings and additional CAPTCHA providers (Turnstile, hCaptcha) are still planned. ## Reviews There are no reviews for this plugin. ## Contributors & Developers “ChatHearth – AI Chatbot” is open source software. The following people have contributed to this plugin. Contributors * [ palwp ](https://profiles.wordpress.org/palwp/) * [ Mohammed Al-Madhoun ](https://profiles.wordpress.org/momadhoun/) [Translate “ChatHearth – AI Chatbot” into your language.](https://translate.wordpress.org/projects/wp-plugins/chathearth) ### Interested in development? [Browse the code](https://plugins.trac.wordpress.org/browser/chathearth/), check out the [SVN repository](https://plugins.svn.wordpress.org/chathearth/), or subscribe to the [development log](https://plugins.trac.wordpress.org/log/chathearth/) by [RSS](https://plugins.trac.wordpress.org/log/chathearth/?limit=100&mode=stop_on_copy&format=rss). ## Changelog #### 1.4.8 * Plugin Check (PCP) clean: hide the launcher until OpenAI is ready, and pass WordPress. org plugin checks. #### 1.4.7 * Hide the front-end chat icon until an OpenAI API key is configured under Connectors. #### 1.4.6 * The chatbot can answer questions about the page the visitor is currently viewing. #### 1.4.5 * Replace Google reCAPTCHA v2 with v3. A white, translucent, blurred overlay covers the chat until verification succeeds. #### 1.4.4 * Knowledge base storage is the WordPress database only. No Python, Chroma, Pinecone, or extra server setup. #### 1.4.3 * Clarify that Chroma is an HTTP server (data files on this host are written by that process). Clearer Test vector store errors. Helper script `bin/run-chroma. sh`. #### 1.4.2 * Smooth expand and restore animation for the chat window. #### 1.4.1 * Shop-style product cards in chat (image, current and previous price, Add to cart). * Header control to double the chat window, with a restore control when expanded. * Horizontal, swipe/scrollable product cards when the panel is too narrow. #### 1.4.0 * Knowledge Base (RAG): markdown export of selected site content, admin include/ exclude, incremental reindex. * Vector stores: WordPress database, self-hosted Chroma, or Pinecone. * Always-on website grounding and off-topic refusal, even when RAG is off. * Product comparison in chat and add to WooCommerce cart from the widget. #### 1.3.0 * Renamed plugin to ChatHearth – AI Chatbot (slug `chathearth`) with matching text domain, namespaces, options, REST routes, and asset handles. #### 1.2.0 * Renamed plugin to PalWP – AI Chatbot (slug `palwp-ai-chatbot`) with consistent Option A prefixes. * Stopped reading Connectors API keys via `get_option()`; readiness uses the WordPress AI Client registry. * Documented external services (OpenAI, Google reCAPTCHA) in the readme. * Removed bundled translation files; translations are handled via translate.wordpress. org. #### 1.1.3 * Scroll chat to the latest message when opening the panel after a page reload. #### 1.1.2 * AI provider failures return a generic client message; details go to `debug.log` only when `WP_DEBUG_LOG` is already enabled. #### 1.1.0 * Optional Google reCAPTCHA v2 checkbox on chat (enabled when site + secret keys are set); one solve unlocks chat for about an hour; green status in Protection settings. * Fix: CAPTCHA no longer resets after every message. #### 1.0.9 * Global (site-wide) rate limits with admin escalation email, notice, and optional auto-disable. #### 1.0.8 * Markdown list rendering fixes; settings tabs under Settings ChatHearth – AI Chatbot; provider/model selectors. #### 1.0.0 * Initial release: site-wide widget, settings, OpenAI via Connectors, rate limits. ## Meta * Version **1.4.8** * Last updated **4 days ago** * Active installations **Fewer than 10** * WordPress version ** 7.0 or higher ** * Tested up to **7.1** * PHP version ** 7.4 or higher ** * Tags * [AI](https://wordpress.org/plugins/tags/ai/)[chatbot](https://wordpress.org/plugins/tags/chatbot/) [connectors](https://wordpress.org/plugins/tags/connectors/)[customer support](https://wordpress.org/plugins/tags/customer-support/) [openai](https://wordpress.org/plugins/tags/openai/) * [Advanced View](https://wordpress.org/plugins/chathearth/advanced/) ## Ratings No reviews have been submitted yet. [Your review](https://wordpress.org/support/plugin/chathearth/reviews/#new-post) [See all reviews](https://wordpress.org/support/plugin/chathearth/reviews/) ## Contributors * [ palwp ](https://profiles.wordpress.org/palwp/) * [ Mohammed Al-Madhoun ](https://profiles.wordpress.org/momadhoun/) ## Support Got something to say? Need help? [View support forum](https://wordpress.org/support/plugin/chathearth/)