=== WinaltChat for WooCommerce ===
Contributors: winalttechnologies, fahadali158
Tags: woocommerce, chatbot, live chat, ai, customer support
Requires at least: 6.2
Tested up to: 7.1
Stable tag: 1.23.4
Requires PHP: 7.4
Requires Plugins: woocommerce
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

WinaltChat – AI chatbot and live human chat for WooCommerce. Find products, answer questions, connect customers to your support team.

== Description ==

**WinaltChat** adds a fast, intelligent chat widget to your
WooCommerce store. Customers can search your product catalogue,
get instant answers about shipping and returns, and — when they
need a real person — connect to your support team through a built-in
live chat system, all without leaving your store.

= AI Shopping Assistant =

* **Dual AI Modes** — Use your own API key from Groq — LLaMA
  (Free Tier), ChatGPT (OpenAI), Claude (Anthropic), or Gemini
  (Google) for full conversational AI. No key? The built-in
  *Basic AI* mode runs entirely on your server with zero external
  calls and zero ongoing cost.
* **Smart Product Search** — Intent-aware search across your
  WooCommerce catalogue. Handles typos, synonyms, multilingual and mixed-language
  queries, and follow-up questions naturally.
* **Product Comparisons** — Customers can ask "which is better, the Sony or the
  Samsung?" and get a clear side-by-side comparison
  with prices and key specs from your own catalogue.
* **Store Knowledge Base** — Reads your shipping, returns, contact,
  and about pages to answer policy questions accurately and
  dynamically — no hardcoded answers that break for other stores.
* **Conversation Context** — Remembers context within a session so
  follow-up questions ("does it come in blue?") work naturally.
* **Amazon Affiliate Fallback** — When a product is out of stock,
  optionally suggest an Amazon affiliate link so you still earn a
  commission.

= Live Human Chat =

* **Human Handoff** — When a customer types phrases like "I want
  to talk to a human", "customer service", "live agent", or dozens
  of natural variants, the plugin detects the request and connects
  them to a real person on your team.
* **Admin Live Chats Dashboard** — A dedicated **Live Chats** screen
  in your WordPress admin shows all active, waiting, and closed
  conversations in a two-panel interface. Every handoff request is
  queued here as soon as it happens — keep the tab open to also show
  as instantly online to visitors and connect in real time.
* **Visitor Name Prompt** — Before connecting, the visitor is
  optionally asked for their name. If skipped, they are identified
  as "Visitor #ID" so you can tell conversations apart.
* **Full Conversation Context for Agents** — When a customer is
  handed off, the admin sees the complete prior AI conversation so
  there is no need to ask "how can I help?" twice.
* **Visitor Presence Dot** — A green dot shows the visitor is
  active. It turns grey within 30 seconds if they close the tab.
* **Two-Tier Timeout** — If your team does not respond within
  90 seconds, the visitor sees a friendly patience message. After
  5 minutes of no reply, the chat gracefully falls back to the AI
  assistant with an optional email capture.
* **Intelligent Offline Handling** — When no admin is online the AI
  keeps helping, and the handoff request is still queued in the
  background so it's waiting in your Live Chats list whenever you
  next check — no need to have caught it live. Visitors can also
  optionally leave their email for a follow-up; leads appear with a
  dedicated Leads section and unread badge.
* **Session Management** — Close chats when resolved, or delete
  them permanently. Closed and lead sessions stay visible in
  their own sections until manually removed.
* **Zero External Dependencies** — Live chat runs entirely within
  your WordPress site using secure AJAX polling over the REST API.
  No Pusher, no third-party service, no extra cost.
* **Email Notifications** — Get an email when a customer starts a
  live chat or leaves their contact details while you are offline.

= Privacy & Security =

* All live chat data is stored in your own WordPress database.
  Nothing is sent to an external service.
* Session tokens are 32-character cryptographically random strings
  — not sequential IDs — so sessions cannot be enumerated.
* All endpoints enforce nonces, capability checks, input
  sanitization, output escaping, and rate limiting.
* Message content is sanitized server-side, and rich chat HTML
  (product cards, links, images) is additionally sanitized
  client-side via a bundled copy of DOMPurify before being
  rendered — see "Bundled Libraries" below.

= Bundled Libraries =

* **DOMPurify 3.1.6** — client-side HTML sanitizer, used to safely
  render rich chat content (product cards, links, images).
  Vendored locally at `assets/js/vendor/purify.min.js`; not loaded
  from a CDN. © Cure53 and other contributors. Dual-licensed under
  the Apache License 2.0 and Mozilla Public License 2.0, both
  GPL-compatible. [github.com/cure53/DOMPurify](https://github.com/cure53/DOMPurify)

= Requirements =

* WordPress 6.2 or later
* WooCommerce 7.0 or later (must be installed and active)
* PHP 7.4 or later
* An API key from Groq, OpenAI, Anthropic, or Google *(optional —
  Basic AI and Live Chat both work without one)*

= Support =

* **Support Forum:** [wordpress.org/support/plugin/winaltchat-for-woocommerce](https://wordpress.org/support/plugin/winaltchat-for-woocommerce/)
* **Email:** support@winalttechnologies.com

We aim to respond to all support requests within 48 hours.

== Installation ==

1. Upload the `winaltchat-for-woocommerce` folder to
   `/wp-content/plugins/`, or install directly via the WordPress
   Plugins screen.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Make sure **WooCommerce** is installed and active.
4. Navigate to **WinaltChat → Settings** in the WordPress admin.
5. **AI Mode (optional):** Choose your preferred AI provider and
   enter your API key, or leave blank to use the built-in Basic AI
   mode at zero cost.
6. **Live Human Chat (optional):** Scroll to the Live Human Chat
   section, enable the toggle, set a notification email and agent
   display name. A **Live Chats** item will appear in the sidebar.
7. Every handoff request is queued to this screen even when you're
   away, so you'll never miss one — keep the tab open while you work
   if you'd also like to appear instantly online and connect live.
8. Customise the chat appearance under the **Chat Appearance** tab.

== Screenshots ==

1. General Settings — configure your AI provider, API key, and core preferences.
2. Chat Appearance — customize colors, icons, welcome message, and branding to match your store.
3. Live Chat Management — the admin console for handling active conversations and agents.
4. AI Conversation — the assistant answering a customer's question live on the storefront.
5. Product Recommendations — the AI surfacing matching products in real time during a chat.
6. Knowledge Base Mapping — configure which store pages (Shipping, Returns, About) the AI reads from.

== Frequently Asked Questions ==

= Do I need an API key to use this plugin? =

No. The built-in Basic AI mode handles product search, comparisons,
policy questions, and conversation without any API key or external
service. Real AI mode (Groq, OpenAI, Claude, Gemini) is optional
and improves response quality for complex queries.

= Does Live Human Chat require any external service? =

No. It runs entirely within your WordPress site using the WordPress
REST API. No Pusher, no LiveChat subscription, no third-party
accounts needed.

= How does the admin know a customer is waiting? =

Every handoff request is queued in the Live Chats screen the moment
it happens, so you'll see it whenever you next check — no need to
have been watching at the time. You'll also get an email at your
configured notify address, and a browser notification fires in the
tab itself (if you grant notification permission) when it's open.
Keep the tab open while you work to additionally show as instantly
online, so a visitor connects to you live instead of waiting.

= What happens if no admin is online when a customer asks for help? =

The AI assistant keeps helping the customer seamlessly. A message
explains the team is unavailable, and the customer is offered an
optional email field so you can follow up. No dead ends.

= How long before an unanswered live chat falls back to the AI? =

At 90 seconds of no response, the visitor sees a friendly
"thanks for your patience" message. At 5 minutes, the chat
gracefully returns to AI mode with an email capture option. Both
thresholds are configurable in the Live Human Chat settings.

= Can multiple admins handle chats at the same time? =

Currently any admin with the manage_options capability can see and
reply to all live chats. Multi-agent role management is planned for
a future release.

= How do I remove all plugin data on uninstall? =

Deleting the plugin via the WordPress Plugins screen automatically
removes all WinaltChat settings, options, and live chat database
tables from your site.

= Does it work with my theme? =

Yes. The chat widget is injected into the page footer and uses its
own scoped CSS so it does not conflict with theme styles.

= Will it slow down my site? =

The AI chat widget loads asynchronously and does not block page
rendering. Live chat polling only runs while an active live session
is in progress — normal AI chat and idle pages make zero polling
requests.

== External Services ==

This plugin connects to third-party AI providers only when you
configure an external AI mode and enter your own API key. In Basic
AI mode and during live human chat, no external AI service is used.

**AI Providers (optional — only when an API key is configured)**

Customer messages, recent conversation context, and relevant store
and product context are sent to the AI provider you select so it
can generate a response. No data is sent to these providers when
using Basic AI mode.

* **Groq** — [groq.com](https://groq.com) | [Privacy Policy](https://groq.com/privacy-policy/) | [Terms of Service](https://groq.com/terms-of-service/)
* **OpenAI** — [openai.com](https://openai.com) | [Privacy Policy](https://openai.com/policies/privacy-policy/) | [Terms of Use](https://openai.com/policies/usage-policies/)
* **Anthropic Claude** — [anthropic.com](https://anthropic.com) | [Privacy Policy](https://www.anthropic.com/privacy) | [Terms of Service](https://www.anthropic.com/legal/consumer-terms)
* **Google Gemini** — [ai.google.dev](https://ai.google.dev) | [Privacy Policy](https://policies.google.com/privacy) | [Terms of Service](https://policies.google.com/terms)

**Amazon Associate Program (optional — only when a tag is configured)**

When the Amazon fallback is enabled and no matching product is
found in your store, the plugin generates an Amazon search link
with your Associate tag. No customer data is transmitted to Amazon
by the plugin — the link simply directs the visitor's browser.

* **Amazon** — [amazon.com](https://www.amazon.com) | [Privacy Notice](https://www.amazon.com/gp/help/customer/display.html?nodeId=GX7NJQ4ZB8MHFRNJ)

**Deactivation Feedback (optional — only sent if you respond to the deactivation survey)**

When you deactivate this plugin, an optional short survey asks why.
If you respond (or skip), your site URL, the plugin/WordPress/PHP
version, and whatever you entered in the survey are sent to
Winalt Technologies to help improve the plugin. No personal data is
collected beyond this unless you choose to type it into the free-text
field yourself.

* **Winalt Technologies** — [aisalesmanchatpro.com](https://aisalesmanchatpro.com) | [Privacy Policy](https://aisalesmanchatpro.com/privacy-policy.html)

**Anonymous Usage Tracking (optional — off by default, only sent if you click "Allow")**

On first use, a notice asks permission to send anonymous "still
active" pings to help us understand real-world installs. Nothing is
sent unless you click "Allow" — you can also decline, or change your
choice later from the plugin's General Settings tab. When enabled,
your site URL and the plugin/WordPress/PHP version are sent to Winalt
Technologies once immediately and then roughly once a day for as long
as it stays enabled. No personal or customer data is ever included.

* **Winalt Technologies** — [aisalesmanchatpro.com](https://aisalesmanchatpro.com) | [Privacy Policy](https://aisalesmanchatpro.com/privacy-policy.html)

== Changelog ==

= 1.23.4 =
* Fix: The hybrid handoff's /live-chat/start 403 is now root-caused and fixed — QA isolated it via A/B testing to only occur with an active WordPress login cookie present (e.g. an admin, or a logged-in WooCommerce customer account, browsing the storefront). Cause: WordPress core's own rest_cookie_check_errors() inspects the X-WP-Nonce header on every REST request when a login cookie is present, independent of any route's own checks — a nonce under that header wrong for the current logged-in context (e.g. served from a page-cache fragment shared across visitors) gets the whole request blanket-rejected before our own code ever runs, and refreshing to a nonce for the same wrong context doesn't help. The live-chat widget now sends its nonce under its own header name, which WP core never inspects, sidestepping the collision while keeping full CSRF protection.

= 1.23.0 - 1.23.3 =
* Improve: Live chat handoff is now "hybrid" — every handoff request is queued for the admin's live chat inbox as soon as it happens, regardless of whether an admin happens to have the Live Chats page open at that moment (previously the conversation was simply lost otherwise). Superseded by 1.23.4's actual root-cause fix for the /live-chat/start 403 this surfaced; see that entry.

= 1.22.0 =
* New: "Cheapest [category]" / "most expensive [category]" questions ("What's your cheapest laptop?", "What's the cheapest TV you have?") now filter by the named product type before sorting by price, instead of always showing the cheapest items catalog-wide with no laptop or TV in sight.
* Fix: "What are the reviews like for the Fitness Smartwatch?" and "Are there any reviews for X?" failed to resolve the named product — leading noise words ("reviews", "like", "there") were never stripped, and since they sat BEFORE the product name, the progressive-trim retry (which only drops keywords from the end) never got a chance to remove them. With no prior context this returned a generic "which product?" clarification; with a product previously shown in context, it incorrectly answered about THAT stale product instead of the one actually named.

= 1.20.7 - 1.21.0 =
* Fix: "How many [Product] do you have in stock?" (and without "in stock"/"available" wording) failed to resolve the named product; "What's new in stock?" and "best sellers" misclassification; context/keyword leakage across price-filter and cart-removal requests (now honestly redirects to the cart page); named coupon-code validity questions; shipping/warranty/policy hallucinated pages; product-spec and attribute questions ignoring the description field; savings questions not computing the actual number. New: Quantity/total-cost questions now resolve the named product and compute quantity x price. Also fixed a stale auto-scroll position.

= 1.20.0 - 1.20.6 =
* Fix: Cart-contents questions never actually read the real cart (silently deleted via a WC_Session_Handler validity check — now verifies the cookie's HMAC directly and reads via a plain read-only query); unescaped cart-session table-name DB parameter; hallucinated return-policy page reference; reversed order-status phrasing not recognized; price-filter follow-up discarding prior context and filler-phrase leakage into keyword extraction; gibberish input misclassified as a short product-name query. "Tested up to" bumped to 7.1.

= 1.19.2 - 1.19.14 =
* Fix: Cart-contents questions returned an HTTP 500 due to a WooCommerce session-init crash outside this plugin (a resumed session is now installed as the real `WC()->session` singleton); a discarded honest fallback message on non-200 HTTP responses; "Tell me about the Wireless Gaming Headset" returning 4 loosely-related products instead of the named one; bare-pronoun follow-up scoring, electronics category search, TV stock lookup, category-listing counts.

== Upgrade Notice ==

= 1.2.0 =
Major feature release: Live Human Chat. Two new database tables
are created automatically on first admin page load after upgrade.
No breaking changes to existing AI chat functionality.
