# DataFirefly WhatsApp — Documentation

> Bienvenue dans la documentation du module DataFirefly WhatsApp. Ce guide couvre tout ce dont vous avez besoin pour installer, configurer et exploiter au maximum votre bouton WhatsApp flottant multi-agents sur…

- Page: <https://www.datafirefly.com/documentation/dfwhatsapp/>
- Langue: fr
- Mis à jour le: 2026-07-02
- Autres langues: [en](https://www.datafirefly.com/en/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/documentation/llms.txt>

Bienvenue dans la documentation du module **DataFirefly WhatsApp**. Ce guide couvre tout ce dont vous avez besoin pour installer, configurer et exploiter au maximum votre bouton WhatsApp flottant multi-agents sur PrestaShop 8 et 9.

## Installation

Le module s'installe comme n'importe quel module PrestaShop, en quelques clics.

### Prérequis

- PrestaShop **8.0.x** ou **9.0.x**
- PHP **8.0** ou supérieur (8.1+ recommandé)
- MySQL 5.6+ ou MariaDB 10.3+
- Au moins un numéro WhatsApp (personnel ou Business)

### Étapes d'installation

1. Téléchargez le fichier `dfwhatsapp-v1.0.0.zip` depuis votre espace client DataFirefly
2. Dans le back-office PrestaShop, allez dans **Modules > Module Manager**
3. Cliquez sur **Téléverser un module** en haut à droite
4. Sélectionnez le fichier ZIP et validez
5. Cliquez sur **Installer** quand le module apparaît
6. Cliquez sur **Configurer** pour ouvrir l'écran de paramétrage

**Astuce :** le module crée automatiquement 6 tables dans votre base de données et ajoute deux entrées de menu dans **Vendre > Catalogue** pour la gestion des agents et le dashboard analytics.

## Configuration générale

La page de configuration du module s'organise en 6 onglets pour vous permettre de tout paramétrer sans vous perdre.

### Onglet Général

- **Activer le module** : interrupteur principal, désactive le bouton sur toute la boutique
- **Mode de sélection d'agent** : round-robin, aléatoire, premier disponible, ou manuel
- **Activer le tracking** : nécessaire pour alimenter le dashboard analytics
- **QR code desktop** : affiche un QR code au lieu d'ouvrir WhatsApp Web sur les postes fixes

### Onglet Apparence

- **Position** : quatre coins possibles (bas-droite, bas-gauche, haut-droite, haut-gauche)
- **Couleur** : par défaut le vert WhatsApp `#25D366`
- **Taille de l'icône** : en pixels (défaut 60)
- **Décalage X / Y** : distance depuis le bord de l'écran
- **Animation** : pulse, bounce, shake, ou aucune
- **Label texte** : label optionnel affiché à côté du bouton

### Onglet Messages

Un message pré-rempli distinct pour chaque type de page (produit, panier, catégorie, CMS, commande, accueil), traduit dans les 4 langues incluses.

### Onglet Planning

- **Mode hors-horaires** :
   - `hide` — le bouton disparaît complètement
   - `show_offline` — le bouton reste visible en grisé avec un message d'attente
   - `callback` — un formulaire de rappel remplace la conversation directe
- **Message hors-horaires** : texte affiché quand tous les agents sont offline

### Onglet RGPD

- **Activer le consentement** : affiche un texte de consentement avant chaque ouverture de WhatsApp
- **Texte du consentement** : personnalisable par langue

### Onglet Exclusions

- **Pages exclues** : liste de contrôleurs (ex. `checkout`, `identity`)
- **Catégories exclues** : IDs de catégories séparés par des virgules
- **Produits exclus** : IDs de produits séparés par des virgules

## Gestion des agents

Le cœur du module : c'est ici que vous ajoutez les personnes qui recevront les messages WhatsApp.

### Ajouter un agent

1. Allez dans **Vendre > Catalogue > Agents WhatsApp**
2. Cliquez sur **Ajouter**
3. Renseignez :
   - **Nom** — nom affiché au client (ex. "Alex")
   - **Téléphone** — au format international sans espaces (ex. `33604525981`)
   - **Département** — libre (Support, Ventes, Technique...)
   - **Avatar** — image optionnelle (png, jpg, svg, webp)
   - **Position** — ordre d'affichage en mode manuel
   - **Rôle** — texte traduit dans les 4 langues (ex. "Support technique")
   - **Message personnalisé** — surcharge optionnelle des messages contextuels

### Configurer les horaires d'un agent

Directement dans le formulaire de l'agent, un tableau hebdomadaire vous permet de définir :

- Plusieurs créneaux par jour (ex. 9h00-12h30 + 14h00-18h30)
- Un jour vide = agent offline ce jour-là
- Un agent sans _aucun_ créneau défini est considéré comme toujours en ligne (mode 24/7)

### Ajouter une exception (jour férié, congé)

1. Dans le formulaire de l'agent, section **Exceptions**
2. Renseignez une date de début et une date de fin
3. Ajoutez un libellé optionnel (ex. "Congés d'été")

**À noter :** vous pouvez aussi ajouter des exceptions _globales_ qui s'appliquent à tous les agents en laissant l'ID agent à 0 dans la base de données.

## Variables contextuelles

Les messages pré-remplis supportent 12 variables qui sont remplacées à la volée selon la page où se trouve le client :

- `{product_name}` — nom du produit (fiche produit)
- `{product_url}` — URL complète du produit
- `{product_price}` — prix formaté avec devise
- `{product_ref}` — référence produit
- `{customer_name}` — nom du client si connecté
- `{cart_id}` — ID du panier
- `{cart_total}` — total du panier formaté
- `{cart_summary}` — liste des articles du panier
- `{order_ref}` — référence de la commande
- `{order_total}` — total de la commande
- `{category_name}` — nom de la catégorie en cours
- `{shop_name}` — nom de la boutique

## Modes de routage d'agents

### Round-robin

Le module alterne entre les agents disponibles à chaque nouvelle ouverture, équilibrant naturellement la charge.

### Aléatoire

Un agent est tiré au sort parmi ceux en ligne. Utile quand l'équité entre les agents n'est pas critique.

### Premier disponible

Le premier agent de la liste (selon la position) qui est actuellement en ligne est sélectionné.

### Manuel

Un popup s'affiche au client avec la liste des agents disponibles (avatar, nom, rôle, statut). Le client choisit lui-même son interlocuteur.

## Analytics et RGPD

### Le dashboard

Accessible via **Vendre > Catalogue > WhatsApp Analytics**, il vous montre :

- Total de clics sur la période
- Nombre de visiteurs uniques (via hachage IP)
- Ratio clics par visiteur
- Répartition par jour, par type de page, par agent
- Top 20 des produits déclencheurs de conversations

### Protection des données

**Conformité RGPD :**

- Consentement explicite affiché avant chaque ouverture de WhatsApp
- IP des visiteurs hachée en **SHA-256** avec un sel propre à votre boutique (`PS_SHOP_DOMAIN` + `_COOKIE_KEY_`)
- Aucune donnée personnelle directe stockée
- Aucun cookie tiers déposé

## QR code sur desktop

Sur les ordinateurs de bureau, plutôt que d'ouvrir WhatsApp Web (qui nécessite un scan systématique du QR code chez le client), vous pouvez activer le mode QR code direct :

- Le module génère un QR code contenant le lien `wa.me` avec le message pré-rempli
- Le client scanne avec son téléphone
- WhatsApp s'ouvre directement sur son mobile avec le message prêt à envoyer

Ce mode maintient la conversation sur le canal préféré du client sans friction supplémentaire.

## Formulaire de rappel

Quand tous vos agents sont hors ligne et que vous avez choisi le mode `callback` :

1. Le client voit un formulaire à la place de la conversation habituelle
2. Il renseigne son nom, son téléphone et un message optionnel
3. La demande est stockée dans la table `ps_dfwhatsapp_callback` avec statut `pending`
4. Vous pouvez consulter les demandes via phpMyAdmin ou construire un rapport personnalisé

## Multilangue

Le module est livré avec 4 langues complètes : **français, anglais, espagnol, allemand**. Tous les textes visibles côté client sont traduits :

- Messages contextuels par page
- Texte de consentement RGPD
- Message de popup de bienvenue
- Labels d'agents (rôle, statut)
- Interface du formulaire de rappel
- Message hors-horaires

Vous pouvez également définir un **rôle** et un **message personnalisé** différents pour chaque langue et chaque agent, directement depuis le formulaire de l'agent en changeant l'onglet de langue.

## Compatibilité

- PrestaShop **8.0.x, 8.1.x, 8.2.x, 9.0.x**
- PHP **8.0 à 8.3**
- Multiboutique **oui** (configurations distinctes par boutique)
- Multilangue **oui** (Polylang non requis)
- Cache **compatible** (Hummingbird, LSCache, Redis)
- Override de classe core : **aucun**

## Dépannage

### Le bouton ne s'affiche pas

1. Vérifiez que le module est activé dans **Général**
2. Vérifiez qu'au moins un agent existe avec le statut _Actif_
3. Vérifiez que la page en cours n'est pas dans la liste des exclusions
4. Videz le cache PrestaShop (**Paramètres avancés > Performances**)
5. Videz le cache navigateur (Ctrl+Shift+R)

### Le clic sur le bouton ne fait rien

1. Ouvrez la console navigateur (F12) et vérifiez qu'il n'y a pas d'erreur JavaScript
2. Vérifiez qu'aucun autre module ne bloque le JS du module
3. Vérifiez que `dfwhatsapp.js` est bien chargé dans le HTML

### Les statistiques ne s'incrémentent pas

1. Vérifiez que le tracking est activé dans **Général**
2. Vérifiez qu'aucun bloqueur de publicité côté client ne filtre l'URL `module/dfwhatsapp/track`
3. Consultez la table `ps_dfwhatsapp_click` pour voir si les événements arrivent

### Erreur SQL "LIMIT 1 LIMIT 1"

Corrigé en version 1.0.1. Mettez à jour votre module vers la dernière version depuis votre espace client DataFirefly.

## Support et mises à jour

- Support par email : [hello@datafirefly.com](mailto:hello@datafirefly.com)
- Mises à jour incluses pendant 12 mois depuis votre espace client
- Compatibilité PS 8 → 9 assurée sans surcoût

## Changelog

### 1.0.0 — 13 mai 2026 — Lancement

- Version initiale publique
- Multi-agents avec quatre modes de routage
- Planning hebdomadaire par agent avec exceptions
- Popup de bienvenue, QR code desktop, formulaire de rappel
- Consentement RGPD natif et analytics avec IP hachée
- Quatre langues : FR, EN, ES, DE
- Compatible PrestaShop 8.0+ et 9.0+