=== Chitty – AI Live Chat ===
Contributors: mubashirhassan
Tags: live chat, ai chat, chatbot, whatsapp, lead capture
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI-powered live chat for WordPress. Human-like replies via Claude, GPT-4, or OpenRouter. Lead capture, language detection & WhatsApp handoff.

== Description ==

**Chitty** is a free, self-hosted AI live chat plugin for WordPress. It turns your website into a 24/7 intelligent support agent — replying to visitors in real time, capturing leads, detecting their language automatically, and handing off to WhatsApp when a human touch is needed.

No monthly SaaS fees. No data leaves your server (except to your chosen AI provider). Everything is stored in your own WordPress database.

= 🤖 AI Providers — Your Choice =

* **Anthropic Claude** (claude-haiku-4-5, claude-sonnet) — fastest, most natural replies
* **OpenAI GPT-4o / GPT-4o-mini** — familiar and powerful
* **OpenRouter (Free models)** — 100% free AI replies, no API key needed for basic use

= ✨ Core Features =

* **Human-like typing simulation** — realistic typing delays, micro-pauses, and flicker so replies feel natural, not robotic
* **20+ language auto-detection** — detects the visitor's language from their message text and replies in the same language
* **Lead capture form** — collect name, email, and phone before or during chat; all leads saved to your WP admin
* **Proactive messages** — automatically send timed messages to visitors who haven't started chatting yet
* **WhatsApp handoff** — one-tap button to continue the conversation on WhatsApp (configurable trigger threshold)
* **Knowledge base** — fill in your business name, products, pricing, hours, FAQs, and policies so the AI answers accurately
* **Auto site crawl** — automatically reads your published pages and posts to build context for AI replies; refreshes daily and on every publish
* **WooCommerce integration** — tracks which chat sessions lead to purchases and shows revenue attribution in the dashboard
* **Chat ratings** — visitors can rate individual AI messages (thumbs up/down)
* **FAQ quick-reply chips** — show clickable FAQ buttons so visitors can get answers without typing
* **Operator personas** — give the AI a human name (Sarah, Emma, etc.) to make it feel more personal
* **Online/Offline hours** — schedule when the widget shows as "Online" and set a custom offline message
* **Color themes & full customization** — 6 preset color themes or fully custom primary/accent colors
* **Fully responsive widget** — looks great on mobile, tablet, and desktop
* **Admin reply mode** — override the AI and reply manually from the WP admin dashboard
* **CSV export** — export all chat sessions and leads to CSV for CRM import
* **IP anonymization** — optionally anonymize IP addresses for stricter GDPR compliance
* **IP geolocation** — optional country/city detection via ip-api.com (disabled by default; opt-in from settings)
* **GDPR tools** — built-in integration with WordPress's personal data export and erasure tools (Tools → Export/Erase Personal Data)
* **Sound notifications** — optional ping sound when a new message arrives
* **No monthly fees** — the plugin is free; you only pay your AI provider's API costs (or use free OpenRouter models)

= 🏪 Perfect For =

* E-commerce stores (answer product questions, handle returns)
* Clinics & service businesses (booking inquiries)
* Agencies & freelancers (qualify leads automatically)
* Restaurants (hours, menu, delivery questions)
* Education businesses (course info, enrollment)
* Any business that gets repetitive enquiries

= 🔒 Privacy & Data =

Chitty stores all chat data (sessions, messages, leads) in **your own WordPress database**. No data is sent to the plugin developer's servers. Chat messages are sent to your chosen AI provider (Anthropic, OpenAI, or OpenRouter) to generate replies — please review their respective privacy policies and disclose this usage to your visitors.

For full details, see our [Privacy Policy](https://www.mubashirhassan.com/chitty-privacy-policy.html).

= 🛠 External Services =

This plugin optionally connects to the following external services:

* **Anthropic API** (api.anthropic.com) — for Claude AI replies. Requires an API key configured by the site owner. [Privacy Policy](https://www.anthropic.com/privacy)
* **OpenAI API** (api.openai.com) — for GPT-4 replies. Requires an API key configured by the site owner. [Privacy Policy](https://openai.com/privacy/)
* **OpenRouter API** (openrouter.ai) — for free and paid AI model routing. Requires an API key configured by the site owner. [Privacy Policy](https://openrouter.ai/privacy)
* **NVIDIA NIM API** (integrate.api.nvidia.com) — for NVIDIA-hosted AI model replies. Requires an API key configured by the site owner. [Privacy Policy](https://www.nvidia.com/en-us/about-nvidia/privacy-policy/)
* **Serper.dev** (google.serper.dev) — optional real-time web search for AI replies. Disabled by default; requires an API key and must be enabled in plugin settings (AI Settings → Web Search). [Terms of Service](https://serper.dev/terms) | [Privacy Policy](https://serper.dev/privacy)
* **SerpAPI** (serpapi.com) — optional real-time web search for AI replies. Disabled by default; requires an API key and must be enabled in plugin settings (AI Settings → Web Search). [Legal (Terms &amp; Privacy)](https://serpapi.com/legal)
* **Brave Search API** (api.search.brave.com) — optional real-time web search for AI replies. Disabled by default; requires an API key and must be enabled in plugin settings (AI Settings → Web Search). [Privacy Policy](https://brave.com/privacy/browser/)
* **AllOrigins CORS proxy** (api.allorigins.win) — used by the Auto-Fill Knowledge Base feature to fetch the content of a URL entered by a site administrator. Only called when an admin manually triggers the auto-fill action in the plugin settings; the entered URL is sent to AllOrigins to retrieve page content. No visitor data is ever sent to AllOrigins. [Terms of Service](https://allorigins.win/) | [Privacy Policy](https://allorigins.win/)
* **ip-api.com** — for visitor geolocation (country/city from IP). Disabled by default; must be explicitly enabled in plugin settings (Behavior → Privacy). [Terms](https://ip-api.com/docs/legal)
* **WhatsApp (Meta)** — optional human handoff link opened by the visitor in their own WhatsApp app. No data is sent by the plugin to WhatsApp servers. [Privacy Policy](https://www.whatsapp.com/legal/privacy-policy)

All external service connections are optional and controlled from the plugin settings (Chitty → Settings). No external service is contacted without the site owner explicitly configuring and enabling it.

== Installation ==

= Automatic Installation (Recommended) =

1. Log in to your WordPress admin panel
2. Go to **Plugins → Add New**
3. Search for **"Chitty AI Live Chat"**
4. Click **Install Now**, then **Activate**
5. Go to **Chitty → Settings** in your admin menu
6. Enter your AI provider API key (or choose a free OpenRouter model)
7. Fill in your Knowledge Base with your business info
8. The chat widget will appear on your site immediately

= Manual Installation =

1. Download the plugin ZIP from WordPress.org
2. Go to **Plugins → Add New → Upload Plugin**
3. Upload the ZIP file and click **Install Now**
4. Activate the plugin
5. Go to **Chitty → Settings** to configure

= Minimum Requirements =

* WordPress 5.8 or higher
* PHP 7.4 or higher
* MySQL 5.6 / MariaDB 10.1 or higher
* An API key from Anthropic, OpenAI, or OpenRouter (OpenRouter has free models)

== Frequently Asked Questions ==

= Is this plugin really free? =

Yes. The plugin itself is 100% free with no subscription. You only pay your chosen AI provider for API usage. OpenRouter offers completely free models, so you can run Chitty at zero cost.

= Do I need technical skills to set it up? =

No. The plugin includes a 4-step setup wizard that walks you through configuration. Most users are live in under 5 minutes.

= Which AI provider should I choose? =

For the best, most natural-sounding replies, we recommend **Anthropic Claude Haiku** — it's fast, affordable, and produces human-like responses. For a free option, use **OpenRouter** with a free model like arcee-ai/trinity-large-preview.

= Does the AI know about my products and services? =

Yes. Fill in the **Knowledge Base** section in plugin settings (business name, products, pricing, hours, FAQs). You can also enable **Auto Site Crawl** which automatically reads your published pages and posts to build context.

= Is my data safe? =

All chat data is stored in your own WordPress database on your own server. The plugin developer does not have access to your chat data. Messages are sent to your AI provider to generate replies — please review your AI provider's privacy policy and disclose this to your visitors.

= Does it work with WooCommerce? =

Yes. Chitty integrates with WooCommerce to track which chat sessions result in purchases, showing revenue attribution in the dashboard.

= Can I reply manually instead of using AI? =

Yes. The admin dashboard includes a live chat view where you can manually type replies, which are delivered to the visitor in real time (polling every 8 seconds).

= Does it support multiple languages? =

Yes. Chitty auto-detects the visitor's language from their message text and instructs the AI to reply in the same language. 20+ languages are supported.

= Is it GDPR compliant? =

Yes. Chitty registers with WordPress's built-in personal data tools. You can export or erase any visitor's data from **Tools → Export Personal Data** and **Tools → Erase Personal Data** in your WordPress admin.

= Can I use this on multiple sites? =

Yes. The GPLv2 license allows unlimited installations.

= What happens when I uninstall the plugin? =

When you delete the plugin, an uninstall routine removes all plugin settings and database tables (wpc_sessions, wpc_chats, wpc_ratings), permanently deleting all stored chat data.

= Where can I get support? =

Post in the [WordPress.org support forum](https://wordpress.org/support/plugin/chitty/) or visit [mubashirhassan.com](https://mubashirhassan.com).

== Screenshots ==

1. **Chat Widget** — the floating chat bubble and open widget as visitors see it on your site
2. **Admin Dashboard** — live sessions, lead stats, and conversation history
3. **Settings — AI Provider** — choose between Claude, GPT-4, and OpenRouter free models
4. **Settings — Knowledge Base** — fill in your business info so the AI answers accurately
5. **Settings — Widget Design** — color themes, branding, position, and behavior options
6. **Leads Manager** — all captured leads with name, email, phone, country, and chat history
7. **Proactive Messages** — configure timed outreach messages for visitors who haven't chatted yet
8. **WhatsApp Handoff** — seamlessly continue conversations on WhatsApp

== Changelog ==

= 2.0.1 =
* Fix (CRITICAL): `wpc_kb_learned` table schema was missing `question_hash` and `source_chat_msg_index` columns referenced by the daily auto-learn job — every run was silently failing with "Unknown column" errors. Schema now created correctly and existing installs are auto-migrated on next admin load.
* Fix (CRITICAL): `wpc_sessions` table was missing the four sentiment columns (`sentiment_last`, `sentiment_score`, `sentiment_updated_at`, `sentiment_flagged`) that the chat handler tries to UPDATE when sentiment analysis is enabled — caused silent DB errors. Added auto-migration.
* Fix (Security): `wpc_rate_limit()` reset the transient TTL on every increment, which let an attacker keep the rate-limit window open indefinitely by trickling requests. Window start time is now tracked separately so the limit always applies to the originally intended interval.
* Fix (Security): Email `From:` and `List-Unsubscribe:` headers built from `site_name` / `admin_email` / unsubscribe URL were not sanitised against CR/LF — a tainted option value could inject extra SMTP headers. Added `wpc_safe_header()` helper that strips CR, LF, NUL and their URL-encoded variants from header components.
* Fix: `$data` variable was used in `wpc_api_lead()` before being initialised, generating a PHP 8 "Undefined variable" warning on every lead capture submission.
* Fix: Replaced all six `current_time('timestamp')` calls with `current_time('U')` — the `'timestamp'` form has been deprecated since WordPress 5.3 and emits a `_deprecated_argument` notice.
* Fix: `wpc_maybe_migrate_tables()` now bails gracefully if the base `wpc_sessions` table does not exist yet (e.g. early `admin_init` before activation completes), avoiding a noisy DB error.

= 2.0.0 =
* Fix: Corrected broken Serper.dev URLs — `/terms-of-service` → `/terms`, `/privacy-policy` → `/privacy` (both returned 404)
* Fix: Replaced broken SerpAPI separate terms/privacy URLs (both returning Cloudflare 522/525 errors) with the single working combined legal page `serpapi.com/legal`
* Fix: PHP syntax error in `wpc_page_logs()` — missing `?>` close tag between `wp_add_inline_style()` call and HTML output (caused fatal parse error on line 5227)
* Fix: Database error `wp_wpc_chat doesn't exist` in `wpc_api_lead()` — wrong table name `wpc_chat` corrected to `wpc_chats` (fixes broken lead notification emails)

= 1.2.6 =
* Fix: Added wpc_sanitize_color() helper — color settings now validated as strict hex (#RGB / #RRGGBB) at both save time and output time in email templates
* Fix: Appearance settings save now uses wpc_sanitize_color() for all four color fields instead of sanitize_text_field()
* Fix: All three email/HTML templates that interpolate the primary color into CSS now sanitize it with wpc_sanitize_color() before string building
* Fix: Remaining two unescaped echo instances — currency symbol (esc_html) and CSS percentage width (intval) — now properly escaped
* Fix: All nine raw <style> blocks in admin pages converted to ob_start() / wp_add_inline_style() pattern (no raw <style> tags in admin screens)
* Fix: AJAX mock-request wrappers for fill-kb, send-email, and unsubscribe now sanitize inputs at the wrapper level as defense-in-depth
* Fix: Public wpc_ajax_unsubscribe() handler now uses sanitize_text_field() on $_GET values before passing to wpc_api_unsubscribe()

= 1.2.5 =
* Fix: Added AllOrigins CORS proxy disclosure to readme.txt External Services section (WordPress.org Guideline #7)
* Fix: Updated broken Serper.dev and SerpAPI privacy/terms URLs in readme.txt
* Fix: All remaining unescaped admin_url(), wp_nonce_url(), and wpc_opt() outputs now wrapped with esc_url() or esc_attr()
* Fix: REST endpoints /wpc/v1/fill-kb, /wpc/v1/lead-outreach, and /wpc/v1/send-email now require current_user_can('manage_options') in addition to nonce verification
* Fix: /wpc/v1/summarize now validates session_key ownership before processing
* Fix: wpc_ajax_lead_outreach_handler() now includes check_ajax_referer() nonce verification
* Fix: wpc_ajax_fill_kb_handler() now includes check_ajax_referer() nonce verification
* Fix: wpc_api_fill_kb() from AJAX handler: nonce added to JS caller
* Fix: Removed direct require_once of WordPress core PHPMailer file; access $phpmailer via wp_mail action hook instead
* Fix: wpc_api_nvidia_proxy() now sanitizes individual message content fields from php://input

= 1.2.4 =
* Fix: uninstall.php now clears all three remaining cron events (wpc_drip_send, wpc_auto_learn_daily, wpc_cart_abandon_scan)
* Fix: uninstall.php now drops the wpc_drip table on plugin deletion
* Fix: readme.txt short description trimmed to under 150 characters
* Fix: Two unescaped echo wpc_opt() calls now use absint() and esc_attr() respectively
* Fix: Large options (wpc_kb_crawl_cache, wpc_kb_crawl_updated, wpc_system_prompt) now stored with autoload=no to prevent loading on every page
* Fix: Added rate limiting to public REST endpoints /wpc/v1/lead (20/10min) and /wpc/v1/rate (60/min)

= 1.2.3 =
* Fix: Added missing external service disclosures to readme.txt — NVIDIA NIM API, Serper.dev, SerpAPI, and Brave Search API (WordPress.org Guideline #7)
* Fix: Updated Privacy Policy section in readme.txt and in-plugin privacy policy content to cover all external services including web search providers
* Fix: Removed superlative language from plugin header description (WordPress.org Guideline #3)
* Fix: Admin notice after site crawl now checks manage_options capability and sanitizes request parameters
* Fix: Replaced hardcoded version string in admin footer with CHITTY_VERSION constant
* Update: Bumped Tested up to: 7.0

= 1.2.2 =
* Fix: Removed hardcoded developer attribution from chatbot system prompt (WordPress.org Guideline compliance)
* Fix: All admin JavaScript now enqueued via wp_register_script/wp_enqueue_script/wp_add_inline_script

= 1.0.1 =
* Fix: "Powered by Chitty" footer credit now disabled by default (opt-in per WordPress.org Guideline #10)
* Fix: IP geolocation via ip-api.com now disabled by default; must be explicitly enabled in Behavior → Privacy settings (opt-in per WordPress.org Guideline #7)
* Fix: Removed forced footer credit override that ran on every page load
* Improvement: Added "Enable IP Geolocation" toggle in Behavior → Privacy settings with clear disclosure notice

= 1.0.0 =
* Initial release
* AI reply generation via Anthropic Claude, OpenAI GPT-4, and OpenRouter free models
* Human-like typing simulation with realistic delays and micro-pauses
* Auto language detection from message text (20+ languages)
* Lead capture form (name, email, phone) with admin dashboard
* Knowledge base with auto site crawl (pages, posts, products)
* Proactive timed messages engine
* WhatsApp handoff button with configurable trigger
* WooCommerce revenue attribution tracking
* Post-chat message ratings (thumbs up/down)
* FAQ quick-reply chips
* Online/offline hours scheduling
* 6 color presets + fully custom color picker
* IP geolocation via ip-api.com (opt-in, disabled by default)
* IP anonymization option for GDPR
* GDPR personal data export and erasure (WordPress core integration)
* Admin manual reply mode with real-time polling
* CSV export for leads and chat sessions
* Sound notifications
* Operator persona names
* 4-step setup wizard
* Full mobile-responsive widget
* "Powered by Chitty" footer credit disabled by default (opt-in per WordPress.org guidelines)

== Upgrade Notice ==

= 2.0.0 =
Compliance fix: corrected broken legal page URLs for Serper.dev (404) and SerpAPI (Cloudflare errors) in readme.txt. No functional changes.

= 1.2.6 =: color settings now validated as hex-only to prevent CSS injection in emails; all admin-page CSS moved to wp_add_inline_style(); remaining unescaped outputs fixed; AJAX wrappers sanitize inputs at wrapper level.

= 1.2.5 =
Security and compliance update: fixes all unescaped outputs, tightens REST API permission checks to require manage_options, adds nonce checks to AJAX handlers, and adds AllOrigins disclosure to readme.

= 1.2.4 =
Security and cleanup update: missing cron events and database table now removed on uninstall; rate limiting added to public API endpoints; performance fix for large options.

= 1.2.3 =
Compliance update: Added missing external service disclosures for NVIDIA NIM and web search APIs. No functional changes.

= 1.0.1 =
Important compliance update: IP geolocation and "Powered by Chitty" footer credit are now disabled by default. You can re-enable them in Chitty → Behavior → Privacy settings.

= 1.0.0 =
Initial release. No upgrade needed.

== Privacy Policy ==

Chitty stores chat session data, lead information, and message history in your WordPress database. No data is sent to the plugin developer's servers.

When AI reply generation is enabled, visitor chat messages are transmitted to your chosen AI provider (Anthropic, OpenAI, OpenRouter, or NVIDIA NIM) to generate responses. These connections require explicit configuration by the site owner.

When real-time web search is enabled, visitor chat messages (or search queries derived from them) are transmitted to your chosen search provider (Serper.dev, SerpAPI, or Brave Search API). This feature is disabled by default and requires an API key and explicit opt-in in plugin settings (AI Settings → Web Search).

IP geolocation (via ip-api.com) is **disabled by default**. It must be explicitly enabled in plugin settings (Chitty → Behavior → Privacy → Enable IP Geolocation). When enabled, visitor IP addresses are sent to ip-api.com to detect country and city.

The "Powered by Chitty" footer credit in the chat widget is **disabled by default** and must be explicitly enabled by the site owner. No external links are embedded without the site owner's opt-in.

As the site owner, you are the data controller and are responsible for disclosing these data practices to your visitors.

Full privacy policy: https://www.mubashirhassan.com/chitty-privacy-policy.html
