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

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

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

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
• 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+