# WhatsApp Commerce Suite — Guide d'installation et de configuration

> Présentation DataFirefly WhatsApp Commerce Suite transforme WhatsApp en canal de vente complet pour WooCommerce via l'API Meta Cloud officielle. Le plugin comprend 4 modules activables indépendamment : synchronisation du catalogue…

- Page: <https://www.datafirefly.com/documentation/dfwhatsappcommerce/>
- Langue: fr
- Mis à jour le: 2026-09-01
- Autres langues: [en](https://www.datafirefly.com/en/documentation/dfwhatsappcommerce/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsappcommerce/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsappcommerce/index.md), [it](https://www.datafirefly.com/it/documentation/dfwhatsappcommerce/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwhatsappcommerce/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsappcommerce/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwhatsappcommerce/index.md)
- Index: <https://www.datafirefly.com/documentation/llms.txt>

## Présentation

DataFirefly WhatsApp Commerce Suite transforme WhatsApp en canal de vente complet pour WooCommerce via l'API Meta Cloud officielle. Le plugin comprend 4 modules activables indépendamment : synchronisation du catalogue Meta Commerce, prise de commande conversationnelle, relance de panier abandonné, et lien de paiement signé.

Prérequis : WordPress 6.2+, WooCommerce 8.0+, PHP 7.4+, un compte WhatsApp Business avec numéro vérifié dans Meta Business Suite, et un site accessible en HTTPS (obligatoire pour le webhook Meta).

## Installation

1. Téléchargez `dfwhatsappcommerce-1.0.1.zip` depuis votre compte client DataFirefly.
2. Dans wp-admin, allez dans **Extensions → Ajouter → Téléverser une extension**, sélectionnez le ZIP et cliquez sur **Installer maintenant**.
3. Activez l'extension. Un nouveau menu **WhatsApp** apparaît dans la barre latérale de l'administration.

À l'activation, le plugin crée 5 tables SQL préfixées `dfwc_` (conversations, messages, paniers abandonnés, log catalogue, journaux) et planifie 3 événements cron : traitement des paniers toutes les 15 minutes, nettoyage des logs quotidien, et synchronisation catalogue par lots toutes les heures.

## Prérequis côté Meta

Avant de configurer le plugin, réunissez ces 5 valeurs depuis [Meta Business Suite](https://business.facebook.com) :

- **Phone Number ID** — WhatsApp → Configuration API → votre numéro
- **WhatsApp Business Account ID** — visible dans les paramètres du compte WhatsApp Business
- **Catalog ID** — Commerce Manager → votre catalogue → Paramètres
- **Access Token permanent** — créez un utilisateur système dans Business Settings → Users → System Users, attribuez-lui les autorisations `whatsapp_business_messaging` et `whatsapp_business_management` ainsi que `catalog_management`, puis générez un jeton sans expiration
- **App Secret** — Meta for Developers → votre application → Paramètres → Général

N'utilisez jamais le jeton temporaire de 24h affiché dans l'onglet Démarrage : il expirera et cassera la synchronisation. Créez toujours un jeton d'utilisateur système permanent.

## Configuration du plugin

1. Allez dans **WhatsApp → Réglages**.
2. Dans la section **Identifiants Meta Cloud API**, collez les 5 valeurs récupérées ci-dessus. Le champ **Webhook Verify Token** est prégénéré automatiquement — ne le modifiez que si nécessaire.
3. Renseignez le **Numéro WhatsApp affiché** au format E.164 sans le signe + (exemple : `33612345678`). C'est ce numéro qui sera utilisé pour le bouton flottant et les CTA.
4. Activez les modules souhaités dans la section **Modules**. Vous pouvez commencer par la seule synchronisation du catalogue et activer le reste progressivement.
5. Enregistrez.

## Configuration du webhook Meta

Le webhook permet à Meta d'envoyer les messages entrants et les statuts de livraison à votre site.

1. Ouvrez **WhatsApp → Tableau de bord** dans wp-admin : la **Callback URL** et le **Verify Token** y sont affichés avec des boutons Copier.
2. Dans [Meta for Developers](https://developers.facebook.com), ouvrez votre application → WhatsApp → Configuration → Webhook.
3. Collez la Callback URL et le Verify Token, puis cliquez sur **Vérifier et enregistrer**.
4. Dans la liste des champs, abonnez-vous à **messages**.

La Callback URL a la forme `https://votre-site.com/wp-json/dfwc/v1/webhook`. Chaque requête entrante est validée par signature HMAC SHA-256 avec votre App Secret : les requêtes non signées ou mal signées sont rejetées.

## Test de la connexion

Depuis **WhatsApp → Tableau de bord** :

- **Tester la connexion API** — vérifie vos identifiants en interrogeant votre Phone Number ID et affiche le numéro vérifié.
- **Envoyer un message test** — saisissez un numéro au format E.164 sans + et envoyez un message texte de test.

Si le message test n'arrive pas alors que la connexion est OK, vérifiez que le numéro destinataire a envoyé au moins un message à votre numéro WhatsApp Business dans les dernières 24h, ou utilisez un template HSM approuvé : Meta n'autorise les messages texte libres que dans la fenêtre de service de 24h.

## Module 1 — Synchronisation du catalogue

Trois modes disponibles dans les Réglages :

- **Temps réel** — chaque création, modification, changement de stock ou suppression de produit est immédiatement répercuté sur le catalogue Meta.
- **Par lots** — les modifications sont accumulées et poussées toutes les heures par lots de 50.
- **Manuel** — rien n'est envoyé automatiquement, vous utilisez le bouton de resynchronisation.

Règles de mapping :

- Chaque produit reçoit un `retailer_id` de la forme `wc_{ID}`.
- Les produits variables ne sont pas envoyés tels quels : chaque variation est poussée individuellement avec son propre prix, stock et image.
- Les produits sans image sont ignorés (exigence Meta).
- Le filtre `dfwc_catalog_product_eligible` permet d'exclure des produits par code, et `dfwc_catalog_product_data` de modifier les données envoyées.

Depuis la version 1.0.1, les **Réglages → Synchronisation du catalogue** proposent deux listes de catégories : **Catégories à synchroniser** (laisser vide pour tout envoyer) et **Catégories à exclure**. Les produits sans image sont journalisés avec le statut `skipped` au lieu d'être re-sélectionnés à chaque lot. En mode temps réel, chaque synchronisation est mise en file d'attente dans Action Scheduler (livré avec WooCommerce) : l'enregistrement d'un produit ou la réduction de stock à chaque commande n'attend jamais la réponse de Meta. Vous pouvez suivre ces tâches dans **WooCommerce → État → Actions planifiées**, groupe `dfwhatsappcommerce`.

La page **WhatsApp → Catalogue** affiche les compteurs de réussite et d'erreur, le journal des 50 derniers événements, et le bouton **Lancer la resynchronisation** qui repousse tous les produits éligibles par lots de 100.

## Module 2 — Commande conversationnelle

Le module conversation répond automatiquement aux messages entrants selon une machine à états : `idle → browsing → selecting_qty → reviewing → awaiting_payment`, plus un état `human_handoff`.

Mots-clés reconnus (français et anglais dans la même conversation) :

- `menu` ou `catalogue` — affiche la liste interactive des produits (jusqu'à 30 éléments, connectés au catalogue Meta)
- `panier` ou `cart` — affiche le contenu du panier avec les boutons Payer / Continuer / Vider
- `commander`, `payer` ou `checkout` — génère le lien de paiement
- `humain`, `conseiller` ou `aide` — transfère à un conseiller (e-mail envoyé à l'adresse configurée)
- `reset` ou `annuler` — réinitialise la conversation

Tout autre texte déclenche une recherche libre dans vos produits. Le panier du client est conservé dans la conversation et lié à son compte WooCommerce si son numéro correspond à un `billing_phone` existant.

Le message de bienvenue et le message de fallback sont personnalisables dans les Réglages. La page **WhatsApp → Conversations** liste toutes les conversations et permet de consulter chaque thread dans une vue de type WhatsApp Web.

## Module 3 — Relance de panier abandonné

Fonctionnement :

1. Le plugin capture le panier des visiteurs (session WooCommerce + cookie de secours 7 jours) et rend le champ téléphone obligatoire au checkout.
2. Après le délai d'abandon (60 minutes par défaut), la première relance part. Les relances 2 et 3 suivent selon leurs propres délais (24h et 72h par défaut, exprimés en minutes dans les Réglages).
3. Chaque relance utilise un template HSM Meta configuré par étape. Si le template échoue, un message texte simple est tenté en secours.
4. La troisième relance peut joindre un code promo WooCommerce existant, appliqué automatiquement au checkout via le lien de récupération.
5. Quand le client finalise sa commande, le panier est marqué récupéré et les relances s'arrêtent.

### Création des templates HSM

Dans Meta Business Suite → WhatsApp Manager → Modèles de message, créez 3 templates (par exemple `dfwc_abandoned_cart_1`, `_2`, `_3`) avec :

- Un corps contenant deux variables : `{{1}}` = prénom du client, `{{2}}` = montant du panier
- Un bouton d'action de type URL avec une variable `{{1}}` en fin d'URL, pointant vers `https://votre-site.com/wp-json/dfwc/v1/recover/{{1}}`

Créez chaque template dans les langues de vos clients : le plugin détecte la locale et envoie la bonne version. Une fois les templates approuvés par Meta, renseignez leurs noms dans les Réglages du plugin.

La page **WhatsApp → Paniers abandonnés** affiche le total, les paniers en cours de relance, les paniers récupérés et le taux de récupération.

## Module 4 — Paiement et notifications

Le lien de paiement généré dans la conversation est un jeton signé HMAC (SHA-256, sel WordPress + secret du plugin) contenant le panier, l'expiration et l'identifiant de conversation. Quand le client clique :

1. Le jeton est validé et décodé.
2. Le panier WooCommerce est reconstruit côté serveur.
3. Le téléphone du client est prérempli au checkout.
4. L'URL est nettoyée par redirection.

La durée de validité du lien est configurable (Réglages → Paiement). Un lien expiré affiche un message d'erreur invitant à en redemander un via WhatsApp.

Notifications automatiques (activables individuellement) :

- **Commande confirmée** — envoyée au passage en statut Processing, avec numéro et total.
- **Commande expédiée** — envoyée au passage en Completed, avec le numéro de suivi détecté depuis Shipment Tracking, AfterShip ou la méta `_tracking_number`, et un bouton CTA de suivi.
- **Paiement échoué** — envoyée au passage en Failed, avec un bouton pour retenter le paiement.

Meta n'accepte un message texte libre que dans les 24 heures qui suivent le dernier message du client. Une commande passée par un client qui n'a jamais écrit sur WhatsApp, ou qui l'a fait il y a plus de 24 h, ne peut être notifiée qu'avec un template HSM approuvé. Renseignez donc les trois templates optionnels des **Réglages → Paiement** : **confirmation de commande** (variables {{1}} numéro, {{2}} total), **expédition** ({{1}} numéro, {{2}} numéro de suivi) et **échec de paiement** ({{1}} numéro, {{2}} lien de paiement). Sans template, le plugin envoie un texte libre, qui n'aboutit que dans la fenêtre de 24 h. La notification d'expédition n'est envoyée qu'une fois par numéro de suivi, et les commandes sans produit à expédier reçoivent une confirmation plutôt qu'un message « en route ».

## Bouton flottant et CTA

- **Bouton flottant** — activable dans les Réglages, position au choix parmi les 4 coins, libellé personnalisable, masquable. Le template `templates/frontend/whatsapp-button.php` est surchargeable en le copiant dans `votre-theme/dfwhatsappcommerce/whatsapp-button.php`.
- **CTA fiche produit** — bouton « Commander via WhatsApp » sous le bouton d'ajout au panier, message prérempli avec le nom et le lien du produit.
- **CTA panier** — bouton « Finaliser via WhatsApp » avec le total du panier.
- **CTA checkout** — lien d'aide discret.
- **Shortcode** — `[dfwc_whatsapp_button text="..." message="..."]` pour un placement manuel n'importe où.

Les clics sur tous ces éléments sont poussés dans le `dataLayer` (préfixe `dfwc_`) pour GA4 / Google Tag Manager.

## Journaux et dépannage

La page **WhatsApp → Journaux** affiche tous les événements avec filtres par niveau (debug → critical) et par canal (api, webhook, catalog, conversation, cart, payment). Le niveau de journalisation et la durée de rétention sont configurables. Les logs sont aussi visibles dans WooCommerce → État → Journaux sous les sources `dfwhatsappcommerce-*`.

Problèmes courants :

- **Le webhook ne se vérifie pas** — vérifiez que votre site est en HTTPS avec un certificat valide, que les permaliens ne sont pas en mode « Simple », et que le Verify Token collé chez Meta est identique à celui des Réglages.
- **Les messages entrants n'arrivent pas** — vérifiez que le champ `messages` est bien abonné dans la configuration du webhook Meta, et que l'App Secret est correct (une signature invalide rejette silencieusement les requêtes, visible dans les Journaux canal webhook).
- **La synchronisation catalogue échoue** — vérifiez que le jeton système possède l'autorisation `catalog_management` et que le Catalog ID correspond bien au catalogue lié à votre compte WhatsApp Business.
- **Les relances ne partent pas** — vérifiez que le cron WordPress fonctionne (WP Crontrol permet de visualiser `dfwc_process_abandoned_carts`), et que les templates HSM sont approuvés par Meta.

## Désinstallation

La désactivation du plugin conserve toutes les données. La suppression définitive depuis la page Extensions déclenche `uninstall.php` : les 5 tables sont supprimées, les options et les événements cron effacés. Les commandes WooCommerce créées via WhatsApp ne sont jamais touchées.