=== ThemeVix Direct Chat Button — WooCommerce WhatsApp Chat ===
Contributors: themevix, motaleb
Tags: woocommerce, whatsapp, click to chat, chat button, customer support
Requires at least: 5.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add a WhatsApp click-to-chat button to WooCommerce and WordPress. Pre-filled product messages, analytics, GA4, Gutenberg, and Elementor support.

== Description ==

**ThemeVix Direct Chat Button** helps WooCommerce stores and WordPress sites add a professional **WhatsApp chat button** so customers can contact you in one click. Messages can include product name, price, URL, cart details, and more — perfect for **WhatsApp product enquiry**, order questions, and **customer support**.

*This plugin is not affiliated with, endorsed by, or sponsored by WhatsApp LLC or Meta Platforms, Inc. WhatsApp is a trademark of WhatsApp LLC.*

= Why store owners use it =

* **WhatsApp click to chat** on product, cart, checkout, and shop pages
* **Pre-filled WhatsApp messages** with dynamic placeholders
* **WooCommerce WhatsApp integration** for product, cart, checkout, and archive loops
* **Click analytics dashboard** with KPIs, charts, and CSV export
* **Google Analytics 4 (GA4)** event tracking for button clicks
* **Gutenberg block**, **Elementor widget**, and `[tv_direct_chat]` shortcode
* **GDPR consent** and optional privacy notice
* Works on **any WordPress site** — even without WooCommerce (shortcode, block, floating button)

= WooCommerce WhatsApp button =

When WooCommerce is active, show a **WooCommerce chat button** on:

* Single product pages (multiple positions: before/after add to cart, after summary, after meta)
* Cart page (classic and block cart)
* Checkout page (classic and block checkout)
* Shop and product archive loops (optional)

Hide the button on selected products or categories. Override phone number or message per product in the WooCommerce product editor.

= WhatsApp messaging features =

* **Two WhatsApp numbers** with primary, alternate, or random routing
* Separate messages for product, cart, checkout, and shop/archive pages
* Up to **3 quick-reply template buttons** on product pages
* Optional welcome message and business hours label
* **Message placeholders** for product and cart data (see below)

= Button design =

* Styles: rounded, pill, square, outline
* Sizes: small, medium, large
* Custom button and text colors
* Animations: bounce, pulse, shake, heartbeat
* Hover effects: darken, lighten, glow
* Custom CSS field
* RTL layout support
* Show or hide on mobile and desktop

= Floating WhatsApp button =

Add a simple site-wide **WhatsApp floating button** (bottom-left or bottom-right) with an optional tooltip label. When the Pro add-on’s advanced floating widget is active, the free floating button is replaced automatically.

= Analytics & GA4 =

**Click analytics (built in):**

* Admin dashboard under **TV Direct Chat → Analytics**
* Overview with KPIs: total clicks, daily average, all-time clicks, this month
* Period filters: 7, 30, 90, or 365 days
* Breakdowns by page type, device, button type, and top products
* Daily click trend chart
* **CSV export**
* Optional anonymous click tracking (page type, device, button type, product ID — no IP addresses)

**Google Analytics 4:**

* Configure under **Settings → Google Analytics**
* Send custom WhatsApp click events to your GA4 property
* Measurement ID, custom event name, product/page parameters
* Debug mode for browser console testing

When the optional Pro add-on is active, its analytics and GA4 settings take over and the free analytics menu is hidden.

= Tools & setup =

* **Click-to-chat link generator** with copy button
* **Basic QR code preview** in admin (for testing your chat link)
* **JSON settings import/export**
* **3-step setup wizard** after activation (phone, display options, finish)

= Blocks, shortcodes & Elementor =

* **Gutenberg block:** search for **Chat Button** in the block inserter (`directchat/chat-button`)
* **Elementor widget:** **WhatsApp Chat Button**
* **Shortcode:** `[tv_direct_chat]` (alias: `[directchat_button]`)

Shortcode attributes: `phone`, `text`, `message`, `style`, `color`, `text_color`, `size`, `icon`, `newtab`, `class`

= Privacy & GDPR =

* Optional GDPR consent checkbox before chat links open
* Optional privacy notice under the button with policy URL
* Click analytics stores anonymous event data only (no IP addresses)
* Suggested privacy policy text included for WordPress Privacy Policy guide

= Optional Pro add-on =

A separate premium add-on (sold on [ThemeVix.com](https://themevix.com/themevix-direct-chat-button/), not WordPress.org) adds multi-agent routing, advanced floating widget, lead capture, display rules, scheduling, WooCommerce automation, AI chatbot, and more. The free plugin works fully on its own.

= Message placeholders =

Available in message fields and templates:

* `{product_name}` — Product name
* `{product_price}` — Product price (formatted)
* `{product_url}` — Product permalink
* `{shop_name}` — Site name
* `{product_sku}` — Product SKU
* `{variation}` — Selected variation attributes (variable products; updated via storefront JavaScript)
* `{quantity}` — Selected quantity (variable products; updated via storefront JavaScript)
* `{cart_total}` — Cart total (cart/checkout messages)
* `{cart_count}` — Number of items in cart

= Shortcode examples =

Basic:

`[tv_direct_chat]`

With custom attributes:

`[tv_direct_chat phone="+1234567890" text="Chat on WhatsApp" message="Hi, I need help!"]`

== Installation ==

1. Upload the plugin to `/wp-content/plugins/themevix-direct-chat-button/` or install from the WordPress Plugins screen.
2. Activate **ThemeVix Direct Chat Button**.
3. Complete the **setup wizard** (opens after first activation) or go to **TV Direct Chat → Settings**.
4. Enter your WhatsApp number in E.164 format (e.g. `+12025551234`).
5. Choose button style, display locations, and messages.
6. Optional: enable click analytics under **Analytics → Click Tracking** or GA4 under **Settings → Google Analytics**.

**WooCommerce:** Product, cart, checkout, and shop buttons require WooCommerce. Shortcode, Gutenberg block, and floating button work without WooCommerce.

== Frequently Asked Questions ==

= What phone number format should I use? =

Use E.164 format with country code, no spaces or dashes. Example: `+12025551234`

= Can I use this without WooCommerce? =

Yes. The `[tv_direct_chat]` shortcode, **Chat Button** Gutenberg block, and floating WhatsApp button work on any WordPress site. WooCommerce is required for automatic product, cart, checkout, and shop/archive buttons.

= How do I change the button position on product pages? =

Go to **TV Direct Chat → Settings → Display** and choose **Button Position**.

= Can I customize the pre-filled WhatsApp message? =

Yes. Edit the message fields under **Settings → General** and **Settings → Display**. Use placeholders like `{product_name}` and `{product_price}`.

= Does this work with variable products? =

Yes. The `{variation}` and `{quantity}` placeholders update on the storefront when shoppers change options on variable product pages.

= Does this support WooCommerce block cart and checkout? =

Yes. Cart and checkout buttons support both classic WooCommerce templates and WooCommerce Blocks.

= Does this plugin track clicks? =

Yes, optionally. Enable **Enable Click Tracking** under **Analytics → Click Tracking** or in **Settings → Tools**. Data is stored in your WordPress database. No IP addresses are saved. You can export reports to CSV from the Analytics Overview.

= Does this plugin support Google Analytics 4? =

Yes. Go to **Settings → Google Analytics**, enter your GA4 Measurement ID, and enable tracking. WhatsApp button clicks are sent as custom GA4 events. Use Debug Mode while testing.

= Is this plugin GDPR compliant? =

The plugin includes an optional GDPR consent checkbox and privacy notice. You control the consent text and privacy policy link. Click analytics and GA4 are optional and can be disabled.

= Do I need a WhatsApp or WhatsApp Business account? =

Yes. This plugin creates click-to-chat links that open WhatsApp (`wa.me`). You need an active WhatsApp account linked to the phone number in your settings.

= What is the difference between the free plugin and the Pro add-on? =

The free plugin includes the WooCommerce WhatsApp button, templates, analytics dashboard, GA4, GDPR tools, shortcode, Gutenberg block, Elementor widget, and basic floating button. The optional Pro add-on adds multi-agent support, advanced floating widget, lead capture, display rules, scheduling, WooCommerce automation, and related premium features.

= Is WooCommerce HPOS supported? =

Yes. The plugin declares compatibility with WooCommerce High-Performance Order Storage (HPOS).

== Screenshots ==

1. General settings — WhatsApp numbers, pre-filled messages, cart message, and dynamic placeholders.
2. Appearance settings — button style, size, colors, animations, hover effects, RTL, and custom CSS.
3. Display settings — page visibility, mobile/desktop rules, excluded URLs, and category/product skips.
4. Google Analytics 4 settings — Measurement ID, event name, product/page parameters, and debug mode.
5. Analytics dashboard — KPIs, clicks by page/device/button type, top products, daily trend, and CSV export.
6. Pre-filled WhatsApp message with product name, price, URL, shop name, and SKU from a product click.
7. WhatsApp chat button on a WooCommerce single product page below Add to cart.

== Changelog ==

= 1.2.0 =
* Checkout page WhatsApp button (classic and block checkout)
* Shop and archive loop button support
* 3-step setup wizard after activation
* Full click analytics dashboard (Overview, Click Tracking, KPIs, daily trend chart, CSV export)
* Google Analytics 4 integration with debug mode (Settings tab)
* Click-to-chat link generator, QR preview, and JSON import/export in Tools
* Basic floating WhatsApp button
* Second phone number with alternate/random modes
* Welcome message and business hours label
* Per-product phone, message, and hide overrides
* Elementor **WhatsApp Chat Button** widget
* Works without WooCommerce for shortcode, Gutenberg block, and floating button
* WooCommerce HPOS compatibility declared
* Placeholders: `{variation}`, `{quantity}`, `{cart_total}`, `{cart_count}`

= 1.1.0 =
* Shop/archive loop chat button
* Custom CSS and mobile/desktop visibility toggles
* Settings import/export (JSON)
* Additional message placeholders

= 1.0.0 =
* Initial release
* WhatsApp click-to-chat button for WooCommerce product and cart pages
* Pre-filled messages with placeholders
* Button styles, sizes, colors, animations, and hover effects
* Shortcode and Gutenberg block
* GDPR consent and privacy notice
* Product and category exclusions
* Quick-reply templates and RTL support

== Upgrade Notice ==

= 1.2.0 =
Adds analytics dashboard, GA4 integration, checkout/shop buttons, setup wizard, and Tools. Recommended update for all users.

== External Services ==

This plugin connects to external services only when a feature that requires them is used.

= WhatsApp (wa.me) — required for chat links =

When a visitor clicks a WhatsApp button, their browser opens a URL like:

`https://wa.me/<phone_number>?text=<pre-filled_message>`

The phone number comes from your plugin settings. The message may include product name, price, URL, shop name, SKU, cart total, and related store data from your own site. Data is sent only when the visitor clicks the button.

* Service: [WhatsApp](https://www.whatsapp.com/)
* Terms: [WhatsApp Terms of Service](https://www.whatsapp.com/legal/terms-of-service)
* Privacy: [WhatsApp Privacy Policy](https://www.whatsapp.com/legal/privacy-policy-eea)

= Google Analytics 4 — optional =

When GA4 tracking is enabled in **Settings → Google Analytics**, the plugin loads Google Tag (`googletagmanager.com/gtag/js`) and sends custom click events to your GA4 property using the Measurement ID you provide. Events may include page type, page URL, and product data depending on your settings.

* Service: [Google Analytics](https://analytics.google.com/)
* Terms: [Google Terms of Service](https://policies.google.com/terms)
* Privacy: [Google Privacy Policy](https://policies.google.com/privacy)

= QR Server — optional, admin only =

The Tools tab displays a QR code preview of your chat link using `api.qrserver.com`. This request is made only in the WordPress admin when viewing the QR preview, not on the public storefront.

* Service: [QR Server API](https://goqr.me/api/)
* Privacy: Refer to the QR Server / goQR website for their privacy terms.

== Privacy Policy Suggestions ==

This plugin can store:

* Plugin settings in the WordPress options table
* Anonymous click analytics in a custom database table (`directchat_clicks`) when tracking is enabled — page type, device type, button type, and optional product ID. No IP addresses.
* GA4 event data is processed by Google when GA4 integration is enabled