# DataFirefly WhatsApp — Documentation

> Welcome to the DataFirefly WhatsApp module documentation. This guide covers everything you need to install, configure and get the most out of your multi-agent floating WhatsApp button on PrestaShop 8…

- Page: <https://www.datafirefly.com/en/documentation/dfwhatsapp/>
- Language: en
- Last updated: 2026-07-02
- Other languages: [fr](https://www.datafirefly.com/documentation/dfwhatsapp/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsapp/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsapp/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwhatsapp/index.md), [it](https://www.datafirefly.com/it/documentation/dfwhatsapp/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsapp/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwhatsapp/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

Welcome to the **DataFirefly WhatsApp** module documentation. This guide covers everything you need to install, configure and get the most out of your multi-agent floating WhatsApp button on PrestaShop 8 and 9.

## Installation

The module installs like any other PrestaShop module, in just a few clicks.

### Requirements

- PrestaShop **8.0.x** or **9.0.x**
- PHP **8.0** or higher (8.1+ recommended)
- MySQL 5.6+ or MariaDB 10.3+
- At least one WhatsApp number (personal or Business)

### Installation steps

1. Download the `dfwhatsapp-v1.0.0.zip` file from your DataFirefly account area
2. In the PrestaShop back-office, go to **Modules > Module Manager**
3. Click **Upload a module** in the top right
4. Select the ZIP file and confirm
5. Click **Install** when the module appears
6. Click **Configure** to open the settings screen

**Tip:** the module automatically creates 6 tables in your database and adds two menu entries under **Sell > Catalog** for agent management and the analytics dashboard.

## General configuration

The module configuration page is organized in 6 tabs to help you set everything up without getting lost.

### General tab

- **Enable module**: main switch, disables the button across the whole store
- **Agent selection mode**: round-robin, random, first available, or manual
- **Enable tracking**: required to feed the analytics dashboard
- **Desktop QR code**: shows a QR code instead of opening WhatsApp Web on desktop

### Appearance tab

- **Position**: four possible corners (bottom-right, bottom-left, top-right, top-left)
- **Color**: defaults to WhatsApp green `#25D366`
- **Icon size**: in pixels (default 60)
- **X / Y offset**: distance from the screen edge
- **Animation**: pulse, bounce, shake, or none
- **Text label**: optional label displayed next to the button

### Messages tab

A distinct pre-filled message for each page type (product, cart, category, CMS, order, homepage), translated into all 4 included languages.

### Schedule tab

- **Off-hours mode**:
   - `hide` — the button disappears completely
   - `show_offline` — the button stays visible greyed-out with a waiting message
   - `callback` — a callback form replaces the direct conversation
- **Off-hours message**: text shown when all agents are offline

### GDPR tab

- **Enable consent**: shows a consent text before every WhatsApp opening
- **Consent text**: customizable per language

### Exclusions tab

- **Excluded pages**: list of controllers (e.g. `checkout`, `identity`)
- **Excluded categories**: category IDs separated by commas
- **Excluded products**: product IDs separated by commas

## Agent management

The heart of the module: this is where you add the people who will receive WhatsApp messages.

### Add an agent

1. Go to **Sell > Catalog > WhatsApp Agents**
2. Click **Add**
3. Fill in:
   - **Name** — displayed name to the customer (e.g. "Alex")
   - **Phone** — international format without spaces (e.g. `33604525981`)
   - **Department** — free text (Support, Sales, Technical...)
   - **Avatar** — optional image (png, jpg, svg, webp)
   - **Position** — display order in manual mode
   - **Role** — text translated into 4 languages (e.g. "Technical support")
   - **Custom message** — optional override of contextual messages

### Configure an agent's schedule

Right from the agent form, a weekly table lets you define:

- Multiple slots per day (e.g. 9:00-12:30 + 14:00-18:30)
- An empty day = agent offline that day
- An agent with _no_ defined slot at all is considered always online (24/7 mode)

### Add an exception (holiday, time off)

1. In the agent form, **Exceptions** section
2. Enter a start date and end date
3. Add an optional label (e.g. "Summer holidays")

**Note:** you can also add _global_ exceptions that apply to all agents by leaving the agent ID at 0 in the database.

## Context variables

Pre-filled messages support 12 variables that are replaced on the fly according to the page the customer is on:

- `{product_name}` — product name (product page)
- `{product_url}` — full product URL
- `{product_price}` — price formatted with currency
- `{product_ref}` — product reference
- `{customer_name}` — customer name if logged in
- `{cart_id}` — cart ID
- `{cart_total}` — formatted cart total
- `{cart_summary}` — list of cart items
- `{order_ref}` — order reference
- `{order_total}` — order total
- `{category_name}` — current category name
- `{shop_name}` — store name

## Agent routing modes

### Round-robin

The module rotates between available agents on each new opening, naturally balancing the load.

### Random

An agent is drawn at random from those online. Useful when equity between agents is not critical.

### First available

The first agent in the list (by position) who is currently online is selected.

### Manual

A popup appears to the customer with the list of available agents (avatar, name, role, status). The customer picks their own conversation partner.

## Analytics and GDPR

### The dashboard

Accessible via **Sell > Catalog > WhatsApp Analytics**, it shows you:

- Total clicks over the period
- Number of unique visitors (via IP hashing)
- Clicks per visitor ratio
- Breakdown by day, page type, agent
- Top 20 products triggering conversations

### Data protection

**GDPR compliance:**

- Explicit consent shown before every WhatsApp opening
- Visitor IPs hashed with **SHA-256** using a shop-specific salt (`PS_SHOP_DOMAIN` + `_COOKIE_KEY_`)
- No direct personal data stored
- No third-party cookies set

## Desktop QR code

On desktop computers, rather than opening WhatsApp Web (which requires systematic QR code scanning by the customer), you can enable direct QR code mode:

- The module generates a QR code containing the `wa.me` link with the pre-filled message
- The customer scans with their phone
- WhatsApp opens directly on their mobile with the message ready to send

This mode keeps the conversation on the customer's preferred channel with no extra friction.

## Callback form

When all your agents are offline and you have selected `callback` mode:

1. The customer sees a form instead of the usual conversation
2. They enter their name, phone number and an optional message
3. The request is stored in the `ps_dfwhatsapp_callback` table with status `pending`
4. You can view requests via phpMyAdmin or build a custom report

## Multi-language

The module ships with 4 complete languages: **French, English, Spanish, German**. All customer-facing texts are translated:

- Contextual messages per page
- GDPR consent text
- Welcome popup message
- Agent labels (role, status)
- Callback form interface
- Off-hours message

You can also define a different **role** and **custom message** for each language and each agent, directly from the agent form by switching the language tab.

## Compatibility

- PrestaShop **8.0.x, 8.1.x, 8.2.x, 9.0.x**
- PHP **8.0 to 8.3**
- Multistore **yes** (distinct configuration per store)
- Multi-language **yes** (Polylang not required)
- Cache **compatible** (Hummingbird, LSCache, Redis)
- Core class override: **none**

## Troubleshooting

### The button doesn't show up

1. Check that the module is enabled in **General**
2. Check that at least one agent exists with _Active_ status
3. Check that the current page is not in the exclusion list
4. Clear the PrestaShop cache (**Advanced Parameters > Performance**)
5. Clear the browser cache (Ctrl+Shift+R)

### Clicking the button does nothing

1. Open the browser console (F12) and check for JavaScript errors
2. Check that no other module blocks the module JS
3. Check that `dfwhatsapp.js` is properly loaded in the HTML

### Statistics don't increment

1. Check that tracking is enabled in **General**
2. Check that no client-side ad blocker filters the `module/dfwhatsapp/track` URL
3. Check the `ps_dfwhatsapp_click` table to see if events are arriving

### SQL error "LIMIT 1 LIMIT 1"

Fixed in version 1.0.1. Update your module to the latest version from your DataFirefly account area.

## Support and updates

- Email support: [hello@datafirefly.com](mailto:hello@datafirefly.com)
- Updates included for 12 months from your account area
- PS 8 → 9 compatibility guaranteed at no extra cost

## Changelog

### 1.0.0 — May 13, 2026 — Launch

- Initial public release
- Multi-agent with four routing modes
- Weekly schedule per agent with exceptions
- Welcome popup, desktop QR code, callback form
- Native GDPR consent and analytics with hashed IP
- Four languages: FR, EN, ES, DE
- Compatible with PrestaShop 8.0+ and 9.0+