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

WinaltChat – AI-powered shopping assistant and live human chat for WooCommerce. Find products, answer questions, connect customers to your 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. Keep the tab open to stay
  marked online for visitors.
* **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. Visitors can optionally leave their email for a
  follow-up. Leads appear in the admin Live Chats list 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 rendered via
  textContent in the browser — XSS injection is not possible.

= 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. Keep the **Live Chats** tab open in your browser while you work
   to appear online to visitors requesting a human.
8. Customise the chat appearance under the **Chat Appearance** tab.

== 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? =

Two ways: a browser notification fires in the Live Chats tab (if
you grant notification permission), and an email is sent to your
configured notify address. Keep the Live Chats tab open while
you work to stay marked as online.

= 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)

== Changelog ==

= 1.3.32 =
* Improve: The "Live Human Chat is currently disabled" notice on the
  Live Chats page now matches the visual style of other informational
  notices in the plugin (gradient background, accent border, icon)
  instead of looking like a plain data panel.

= 1.3.31 =
* New: Live Chat settings now has a Send Test Email button to confirm
  wp_mail() is working on your server — shows success or a plain
  error message if delivery fails.
* New: Admin now receives an email notification when a visitor sends
  a new message during a live chat session (rate-limited to once per
  10 minutes per session to avoid inbox spam).
* Fix: Admin console now shows a "visitor left" or "chat closed"
  system note and switches to read-only mode when the session is
  closed or abandoned server-side (e.g. visitor timed out), without
  waiting for a manual page refresh.
* Fix: When a visitor closes their browser tab or navigates away
  during a live session, the admin console now receives an explicit
  "Chat ended by visitor" system note within the next poll cycle
  instead of only showing the presence dot going grey.

= 1.3.30 =
* New: The WinaltChat and Live Chats menu items now show a red
  notification badge with the exact count of unread visitor messages
  waiting for a reply, matching the native WordPress Comments/Plugins
  badge style.

= 1.3.29 =
* Improve: The Live Chats menu item is now always visible in the
  WordPress admin, even when Live Human Chat is turned off. Visiting
  the page while the feature is disabled now shows a friendly message
  with a direct link to enable it in Settings, instead of the menu
  item disappearing entirely.

= 1.3.28 =
* Fix: Admin's own sent messages were being marked as "read" in the
  database at the moment they were sent, regardless of whether the
  visitor had actually seen them. This bypassed the existing
  read-receipt gating logic entirely and caused the admin console to
  always show a blue (read) tick immediately, even when the visitor's
  chat was closed, minimized, or the page had been refreshed. Admin
  messages now correctly start as unread and only turn blue once the
  visitor has genuinely viewed them.

= 1.3.27 =
* Fix: Admin console no longer marks visitor messages as read while
  the admin's browser tab is in the background. Previously, visitor
  message read-state was marked on every poll regardless of whether
  the admin was actually looking at the screen — now gated on tab
  visibility (&seen=1), mirroring the same technique already used for
  the symmetric visitor-side case.

= 1.3.26 =
* Fix: Reduced excessive gap between message text and inline timestamp on
  both outgoing and incoming live-chat bubbles. Spacer widths are now
  calculated to the minimum needed to prevent footer overlap plus a 4–5 px
  breathing gap (outgoing: 52 px, incoming: 32 px; previously both 68 px).

= 1.3.25 =
* Improve: Incoming admin live-chat messages now display their timestamp
  inline at the bottom-right of the bubble (WhatsApp style), matching the
  layout used for outgoing visitor messages. Applied the same inline spacer
  technique — a hidden span reserves the footer's width in the text flow
  so the timestamp never overlaps the message content.

= 1.3.24 =
* Improve: Outgoing live-chat message timestamps now appear inline after
  the message text ends (WhatsApp style) rather than fixed at the
  bottom-right corner. An invisible inline spacer reserves the footer's
  width at the end of the last text line, so the absolutely-positioned
  timestamp and tick slot naturally beside the text on both short and
  long messages without the clipping issues that the float approach had.

= 1.3.23 =
* Fix: Reverted float-based footer approach (caused short messages to
  render with timestamp on a second line). Switched to absolute
  positioning with a min-width guard on the bubble: the bubble is
  always at least 90px wide, ensuring the footer never clips on single-
  word messages while absolute positioning keeps it at the bottom-right
  corner regardless of message length.

= 1.3.22 =
* Fix: Short outgoing live-chat messages (e.g. a single word) no
  longer clip their timestamp/tick footer. Switched from absolute
  positioning to a float-based footer so the bubble's width correctly
  accounts for the footer's own size, matching WhatsApp's actual
  layout behavior instead of an approximation that only worked by
  coincidence on longer messages.

= 1.3.21 =
* Improve: Visitor's outgoing message "read" tick now uses full white
  contrast instead of light blue, since the outgoing bubble color is
  store-configurable and the previous light-blue tick had very low
  contrast against blue-themed bubbles, making the read state hard to
  distinguish from the sent/delivered state.
* Improve: Tightened spacing between message text and the timestamp/
  tick footer on outgoing bubbles to sit closer to the WhatsApp-style
  compact footer rather than appearing as a separate row.

= 1.3.20 =
* Fix: Visitor's own outgoing live-chat messages now show a timestamp
  next to the delivery tick, matching the admin console and standard
  messaging-app conventions.
* Fix: Visitor's outgoing message ticks now reliably turn blue when
  the admin reads them. The real message ID returned by the server on
  send is now used directly instead of relying on the message
  coincidentally reappearing in a later poll batch matched by
  (collision-prone) truncated text content.

= 1.3.19 =
* Fix: Timestamps across admin console and visitor chat now display in
  12-hour format ("2:05 PM") instead of 24-hour. All three formatters
  unified to use { hour: 'numeric', minute: '2-digit', hour12: true }.
* Fix: Admin's own sent messages no longer disappear until a page refresh.
  The premature lastId advancement in sendReply() was excluding the
  just-sent message from the immediately-following poll. Removed it.
* Fix: Admin now only sees blue ticks (message read) when the visitor
  is actively viewing the chat widget with the tab visible. The
  is_read=1 UPDATE is gated on a &seen=1 parameter sent by JS only
  when chatOpen && !document.hidden.
* Fix: Visitor outgoing message ticks now correctly upgrade to blue
  when the admin reads them, even after the poll cursor has advanced
  past those messages. visitor_poll() now returns visitor_read_ids and
  a new updateTicksFromReadIds() method drives the upgrade.
* Fix: Live-chat admin message timestamps now appear bottom-right
  inside the bubble (WhatsApp style) instead of below it. Timestamp
  HTML moved inside .ai-bubble.assistant in formatMessage() and styled
  with position:absolute via .has-timestamp CSS class.

= 1.3.18 =
* Fix: Fixed a fatal error in the visitor live-chat poll endpoint that
  caused every poll request to fail with HTTP 500. The "mark admin
  messages as read" query was missing a required global $wpdb
  declaration and referenced an undefined variable. This was preventing
  visitors from ever receiving admin replies during live chat.

= 1.3.17 =
* Fix: Admin messages sent during live human chat no longer disappear
  from the visitor's chat window. Root cause: incoming admin messages
  were appended directly to the DOM instead of being added to the
  chat's message history, so the next unrelated re-render (e.g. the
  visitor sending a message) wiped them. Admin messages are now part
  of the same message history as everything else and survive all
  subsequent re-renders.

= 1.3.16 =
* Fix: Admin message bubbles now show a WhatsApp-style timestamp and
  grey double-tick (delivered) in the bottom-right corner.
* Fix: Grey ticks turn blue once the visitor has read the message,
  updating live without re-rendering the thread.
* Fix: fetch_messages() now returns is_read so tick state is
  correctly reflected on initial thread load.
* Fix: visitor_poll() now marks admin messages as is_read = 1 so
  the grey-to-blue tick transition is driven by actual visitor reads.

= 1.3.15 =
* Fix: Searches for uncatalogued product types no longer return irrelevant products; relevance gate now correctly returns no-results when no products match the search keyword.

= 1.3.14 =
* Fix: Product searches for uncatalogued items (e.g. "laptops") now return a helpful no-results message instead of irrelevant products.

= 1.3.13 =
* Fix: Message ticks now appear inside the chat bubble
  bottom-right corner (WhatsApp style) — not below it.
* Fix: All visitor messages get ticks, not just the last one.
* Fix: Tick size reduced to match standard messaging apps.
* New: Admin console now shows ticks on sent messages —
  single grey when sent, double blue when visitor is online
  and receiving messages.

= 1.3.12 =
* New: WhatsApp-style message ticks on visitor messages during live human
  chat — single grey tick when sent, double grey when delivered, double
  blue when the agent has read the message. Ticks only appear during live
  sessions, never during normal AI chat.

= 1.3.11 =
* New: Timestamps in live human chat — each admin message shows the send time,
  and a centred time divider appears between messages when more than 5 minutes
  have passed. Times display in the visitor's local timezone. Timestamps are
  shown only during live sessions, not during normal AI chat. The admin console
  also shows timestamps on all messages in the thread.

= 1.3.10 =
* New: Added WordPress Playground blueprint for Live Preview
  on the WordPress.org plugin directory page. Visitors can
  now try a fully working demo without installing anything.
  The demo includes 8 sample products across 5 categories,
  a complete store knowledge base (shipping, returns, contact,
  about), and WinaltChat configured in Basic AI mode so no
  API key is needed.

= 1.3.8 =
* Fix: Replaced store-specific product examples (GFC, Electromax) in readme.txt and code comments with generic international examples suitable for any WooCommerce store worldwide.
* Fix: "Urdu/English mixed queries" replaced with "multilingual and mixed-language queries" in plugin description.

= 1.3.7 =
* Maintenance: Trimmed changelog to WordPress.org 5000 character limit, keeping entries from 1.2.6 onwards.
* Fix: Plugin URI updated to the WordPress.org plugin page.

= 1.3.6 =
* Security: Added per-IP rate limiting (30 requests / 60 seconds) to the AI chat REST endpoint to prevent API credit abuse by automated clients.
* Security: Visitor poll endpoint now verifies the WP REST nonce (via X-WP-Nonce header or ?nonce= query param) in addition to the session token, consistent with all other visitor endpoints.
* Fix: admin.js settings-save buttons now build DOM nodes with textContent / .text() instead of jQuery .html() string concatenation, eliminating a theoretical HTML injection path via malicious translation files.
* Fix: Chat transcript download now passes assistant message content through sanitizeViaDOM() before inserting it into the exported HTML file.
* Fix: readme.txt Tested up to corrected from 7.0 to 6.8.

= 1.3.5 =
* Fix: Bumped minimum WordPress requirement from 6.0 to 6.2 to legitimise use of the %i identifier placeholder in $wpdb->prepare() calls — PHPCS was correctly flagging %i as unsupported below 6.2.

= 1.3.4 =
* Fix: PluginCheck.Security.DirectDB.UnescapedDBParameter warnings resolved — all flagged queries now use the %i identifier placeholder (WordPress 6.2+) for table names instead of PHP string interpolation, eliminating intermediate $sql variables that triggered the sniff.
* Fix: DELETE queries in the admin delete handler replaced with $wpdb->delete() — no manual SQL string construction.
* Note: WordPress.DB.DirectDatabaseQuery.SchemaChange warnings in uninstall.php are advisory-only and expected — Plugin Check always warns on DROP TABLE. They do not block WordPress.org submission.

= 1.3.3 =
* Fix: Plugin Check warnings resolved — all PHPCS checks pass cleanly.
* Fix: readme.txt short description trimmed to a single line under 150 characters.
* Fix: Two DELETE queries in the admin delete handler now use $wpdb->delete() — direct session_id interpolation removed.
* Fix: Remaining UnescapedDBParameter Plugin Check warnings suppressed with inline phpcs:ignore comments where table names are trusted constants and values are prepared.



== 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.
