=== IMPULSA Multi-Agent Chat Router & Analytics ===
Contributors: matiasconchar
Tags: whatsapp, chat, leads, analytics, routing
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 3.1.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Route conversations to multiple agents, apply business rules and measure lead conversion with built-in analytics.

== Description ==

IMPULSA Multi-Agent Chat Router & Analytics is a lead routing and conversion analytics plugin for WordPress sites using WhatsApp. It helps site owners route conversations to multiple agents, apply business rules, measure engagement, and improve lead conversion.

It distributes incoming conversations among multiple agents using configurable routing strategies, applies business rules (business hours, display timing) to decide when and how to show a contact point, and measures the resulting conversations with a built-in, privacy-conscious analytics dashboard — all without any external dependencies.

**This plugin is not affiliated with, endorsed by, sponsored by, or otherwise connected to WhatsApp, Meta, or any of their subsidiaries or affiliates.**

= Why IMPULSA Multi-Agent Chat Router & Analytics? =

* **Multi-agent routing** — distribute conversations across a sales or support team instead of a single number.
* **Conversion analytics** — a built-in dashboard shows clicks, trends, top pages, devices, traffic sources, and per-agent performance.
* **Business rules** — business hours and smart display rules (delay, scroll, exit intent) control when visitors see a contact point.
* **Dynamic messaging** — pre-fill the message with page context and UTM parameters.
* **Privacy-conscious** — internal analytics are aggregated and contain no personal data; optional GA4/GTM tracking is opt-in.
* **No code needed** — configure everything from the WordPress admin panel.
* **Lightweight** — no external libraries, zero performance impact.
* **Secure** — follows WordPress.org standards.

A floating button is the visitor-facing entry point used by the plugin to start a conversation, but the core value is the routing and analytics behind it.

= Multiple Agents & Routing Strategies =

Perfect for businesses with sales or customer support teams:

* Add as many agents as you need, each with their own name and number.
* 4 routing strategies:
  * **Single agent** — classic behavior, one number.
  * **Round Robin** — distributes visitors among agents in rotating order.
  * **Random** — assigns a random agent on each visit.
  * **Selector** — shows an accessible modal so the visitor can choose which agent to contact.
* Analytics per agent: see which agent generates the most conversations.

= Built-in Conversion Analytics =

* Dashboard with KPIs: lifetime total, today, last 7 days, last 30 days.
* 30-day trend chart in native SVG (no Chart.js or external libraries).
* Top WordPress pages generating clicks.
* Breakdown by device and traffic source.
* Date range filter and CSV export.
* Optional `whatsapp_click` event compatible with Google Analytics 4 (gtag) and Google Tag Manager (dataLayer).

= Business Hours & Smart Display Rules =

* **Business hours** — show the contact point only on the days and hours you configure, using your WordPress installation's timezone.
* **Display rules** — control when the floating button appears: immediately, after a delay, after a scroll percentage, or on exit intent.

= Dynamic Messages =

Personalize the message based on the visitor's current page using variables that are replaced automatically:

* `{page_title}` — title of the current page.
* `{current_url}` — full URL of the current page.
* `{utm_source}`, `{utm_medium}`, `{utm_campaign}` — UTM parameters from the URL.

= Floating Chat Button =

The visitor-facing entry point that triggers routing and analytics:

* Contact number with country code in international format.
* Default message up to 500 characters.
* 5 button icon designs (circle, squircle, pulse, gradient, and glass).
* Floating position (top/bottom · left/right) with custom margins.
* Per-device visibility: mobile, tablet, and desktop independently.
* Fully customizable icon color and hover color.
* Optional call-to-action (CTA): hidden, always visible, or on hover.
* Live preview directly in the WordPress admin panel.

= Privacy & Data =

* Internal analytics are **aggregated** (counts per day, page, device, and traffic source) — never per-visitor records.
* The plugin does **not** store visitor IP addresses.
* The plugin does **not** store visitor emails.
* The plugin does **not** store visitor phone numbers.
* The plugin does **not** collect personal data from visitors.
* All internal analytics data stays in your own WordPress database; no third-party analytics service is contacted by the plugin.
* GA4/GTM event tracking is **optional and disabled by default**.
* When enabled, the plugin does **not load any Google script or library**.
* The plugin only pushes a `whatsapp_click` event to the site's existing `window.dataLayer` or calls its existing `window.gtag()` function — and only if the administrator enables the feature and the site already has its own GA4/GTM implementation.
* Site owners are responsible for complying with applicable visitor-consent requirements in their jurisdiction (e.g. GDPR) when enabling GA4/GTM tracking, since the plugin itself does not implement a consent banner.

When a visitor clicks the button, they are redirected to a third-party messaging service (wa.me). That interaction is subject to the recipient service's own privacy policy.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` or install it from **Plugins → Add New** in your WordPress dashboard.
2. Activate the plugin under **Plugins → Installed Plugins**.
3. Go to **IMPULSA Chat Router** in the sidebar menu to configure agents, routing, business rules, and analytics.

== Frequently Asked Questions ==

= Does the plugin store personal data from visitors? =

No. Internal analytics record aggregated counts with non-personal dimensions: page path (no parameters or UTMs), device type (mobile/tablet/desktop), and traffic source category (direct/organic/paid/referral). No IPs, emails, or visitor phone numbers are stored.

= Does it work with cached sites? =

Yes. Click tracking uses the REST API with same-origin validation instead of a nonce, so it works correctly when the page is served from cache (WP Super Cache, W3 Total Cache, LiteSpeed, etc.).

= Can I have multiple contact numbers? =

Yes. You can configure multiple agents and choose how visitors are distributed among them: single agent, round robin, random, or a selector modal they can choose from.

= Is the GA4/GTM event tracking required? =

No. It's disabled by default and must be explicitly enabled by the site administrator. It never loads any Google script — it only pushes an event into your site's own existing `dataLayer`/`gtag` if you already use GA4 or GTM.

= Does it require jQuery or other libraries? =

The frontend runs on vanilla JavaScript — no jQuery or external libraries. The admin panel uses jQuery through WordPress, only for the color picker and live preview.

= What happens when I deactivate the plugin? =

Your data is preserved. The floating button stops showing, but all settings, agents, and analytics remain intact if you reactivate the plugin.

= How do I delete all plugin data? =

When you delete the plugin from **Plugins → Installed Plugins → Delete**, all settings options and the analytics table are automatically removed from the database.

== Screenshots ==

1. Configuration panel with live preview of the chat button.
2. Multiple agents management and routing strategy selection.
3. Analytics dashboard with KPIs, trend chart, and breakdowns.
4. Accessible agent selector modal.

== Changelog ==

= 3.1.2 =
* Renamed plugin to "IMPULSA Multi-Agent Chat Router & Analytics" and updated slug to `impulsa-multi-agent-chat-router` to comply with WordPress.org review guidelines.
* Removed `Plugin URI` temporarily until the new slug is confirmed by WordPress.org.
* Updated text domain to `impulsa-multi-agent-chat-router` throughout.
* Improvement: admin menu, page heading, welcome screen, and About tab now consistently use the new plugin name.
* Improvement: `register_setting()` sanitize callback refactored to a public static method for Plugin Check compatibility.
* Improvement: Privacy & Data section rewritten as explicit, itemized statements (no IP/email/phone storage, no personal data collection, GA4/GTM opt-in with no Google scripts loaded).
* Change: the button icon is now a generic chat mark instead of a third-party brand logo, to comply with trademark guidelines. The 5 design variants, colors and positioning are unchanged.
* Improvement: removed the manual `load_plugin_textdomain()` call — WordPress loads translations automatically for plugins hosted on WordPress.org.
* Improvement: `Tested up to` updated to WordPress 7.0.

= 3.1.1 =
* Improvement: reduced the admin panel to a single, discreet developer credit on the "About" tab; removed the cross-promotion of other developer products.
* Improvement: clarified the Privacy & Data section to explicitly document the optional GA4/GTM event — disabled by default, no scripts loaded, no network requests made by the plugin.

= 3.1.0 =
* New: multiple agents — configure name, country code, and number separately for each agent.
* New: 4 routing strategies — Single agent, Round Robin, Random, and Agent Selector.
* New: accessible agent selector modal — visitors choose who to contact; keyboard-navigable, no external libraries.
* New: per-agent analytics — the dashboard shows which agent drives the most conversations.
* New: welcome screen on first plugin activation.
* New: About tab with plugin and developer information.
* Improvement: live preview simulates Selector mode (opens modal), Round Robin (advances agent per click), and Random (picks randomly).
* Improvement: dynamic message variables documented with descriptions and examples in the settings panel.

= 3.0.0 =
* New: analytics dashboard — KPI cards (lifetime, today, 7 and 30 days), 30-day trend chart in native SVG, top pages by clicks, device and traffic source breakdowns.
* New: date range filter (today, 7/30/90 days, custom) and CSV export.
* New: dimensional data model (`{prefix}wpfwa_events`) with bounded growth.
* Improvement: automatic migration of existing stats; historical totals are preserved.

= 2.1.0 =
* New: redesigned admin panel with instant live preview.
* New: visual design card selector.
* Improvement: 5 refreshed icon designs.
* Improvement: CTA text appears on the opposite side from the edge.

= 2.0.0 =
* New: Google Analytics 4 (gtag) and Google Tag Manager (dataLayer) integration with `whatsapp_click` event.
* New: dynamic messages with variables `{page_title}`, `{current_url}`, `{utm_source}`, `{utm_medium}`, `{utm_campaign}`.
* New: business hours (enabled days and times).
* New: display rules — delay, scroll percentage, and exit intent.
* New: live preview in the admin panel.

= 1.0.0 =
* Initial public release.

== Upgrade Notice ==

= 3.1.2 =
Renames the plugin to "IMPULSA Multi-Agent Chat Router & Analytics" and updates the slug to `impulsa-multi-agent-chat-router`. No settings, agents, or analytics data are affected; internal database options and prefixes are unchanged.
