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 Meta Commerce, prise de commande conversationnelle, relance de panier abandonné, et lien de paiement signé.

Installation

1. Téléchargez dfwhatsappcommerce-1.0.0.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 :

• 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

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

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.

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.

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.