ChatHearth – AI Chatbot

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. Support by Mohammed Al-Madhoun (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.