WhatsApp Commerce Suite — Installation and configuration guide

Overview

DataFirefly WhatsApp Commerce Suite turns WhatsApp into a complete sales channel for WooCommerce, using Meta’s official Cloud API. The plugin ships 4 independently togglable modules: Meta Commerce catalog sync, conversational ordering, abandoned cart recovery, and signed payment link.

Installation

1. Download dfwhatsappcommerce-1.0.0.zip from your DataFirefly customer account.
2. In wp-admin, go to Plugins → Add New → Upload Plugin, select the ZIP and click Install Now.
3. Activate the plugin. A new WhatsApp menu appears in the admin sidebar.

On activation, the plugin creates 5 SQL tables prefixed dfwc_ (conversations, messages, abandoned carts, catalog log, logs) and schedules 3 cron events: cart processing every 15 minutes, daily log cleanup, and hourly batch catalog sync.

Meta prerequisites

Before configuring the plugin, gather these 5 values from Meta Business Suite:

• Phone Number ID — WhatsApp → API Setup → your number
• WhatsApp Business Account ID — visible in your WhatsApp Business account settings
• Catalog ID — Commerce Manager → your catalog → Settings
• Permanent Access Token — create a system user in Business Settings → Users → System Users, grant it the whatsapp_business_messaging, whatsapp_business_management and catalog_management permissions, then generate a non-expiring token
• App Secret — Meta for Developers → your app → Settings → Basic

Plugin configuration

1. Go to WhatsApp → Settings.
2. In the Meta Cloud API credentials section, paste the 5 values gathered above. The Webhook Verify Token field is pre-generated automatically — only change it if needed.
3. Set the Displayed WhatsApp number in E.164 format without the + sign (example: 447911123456). This number powers the floating button and the CTAs.
4. Enable the modules you need in the Modules section. You can start with catalog sync alone and enable the rest progressively.
5. Save.

Meta webhook configuration

The webhook lets Meta deliver incoming messages and delivery statuses to your site.

1. Open WhatsApp → Dashboard in wp-admin: the Callback URL and Verify Token are shown there with Copy buttons.
2. In Meta for Developers, open your app → WhatsApp → Configuration → Webhook.
3. Paste the Callback URL and the Verify Token, then click Verify and save.
4. In the fields list, subscribe to messages.

The Callback URL looks like https://your-site.com/wp-json/dfwc/v1/webhook. Every incoming request is validated with an HMAC SHA-256 signature against your App Secret: unsigned or badly signed requests are rejected.

Testing the connection

From WhatsApp → Dashboard:

• Test API connection — checks your credentials by querying your Phone Number ID and shows the verified number.
• Send a test message — enter a number in E.164 format without + and send a test text message.

Module 1 — Catalog sync

Three modes available in Settings:

• Real-time — every product creation, update, stock change or deletion is immediately reflected on the Meta catalog.
• Batch — changes are accumulated and pushed hourly in batches of 50.
• Manual — nothing is sent automatically; you use the resync button.

Mapping rules:

• Each product gets a retailer_id of the form wc_{ID}.
• Variable products are not sent as-is: each variation is pushed individually with its own price, stock and image.
• Products without an image are skipped (Meta requirement).
• The dfwc_catalog_product_eligible filter lets you exclude products by code, and dfwc_catalog_product_data lets you modify the payload.

The WhatsApp → Catalog page shows success and error counters, the last 50 events log, and the Run resync button which re-pushes all eligible products in batches of 100.

Module 2 — Conversational ordering

The conversation module automatically replies to incoming messages using a state machine: idle → browsing → selecting_qty → reviewing → awaiting_payment, plus a human_handoff state.

Recognized keywords (French and English in the same conversation):

• menu or catalogue — shows the interactive product list (up to 30 items, connected to the Meta catalog)
• cart or panier — shows the cart contents with Pay / Continue / Clear buttons
• checkout, pay or payer — generates the payment link
• human, humain or aide — hands off to an advisor (e-mail sent to the configured address)
• reset or annuler — resets the conversation

Any other text triggers a free-text search across your products. The customer’s cart is kept in the conversation and linked to their WooCommerce account if their number matches an existing billing_phone.

The welcome and fallback messages are customizable in Settings. The WhatsApp → Conversations page lists all conversations and lets you review each thread in a WhatsApp Web-style view.

Module 3 — Abandoned cart recovery

How it works:

1. The plugin captures visitor carts (WooCommerce session + 7-day fallback cookie) and makes the phone field required at checkout.
2. After the abandon threshold (60 minutes by default), the first reminder fires. Reminders 2 and 3 follow their own delays (24h and 72h by default, expressed in minutes in Settings).
3. Each reminder uses a Meta HSM template configured per step. If the template fails, a plain text message is attempted as fallback.
4. The third reminder can attach an existing WooCommerce coupon code, applied automatically at checkout through the recovery link.
5. When the customer completes their order, the cart is marked recovered and reminders stop.

Creating the HSM templates

In Meta Business Suite → WhatsApp Manager → Message Templates, create 3 templates (e.g. dfwc_abandoned_cart_1, _2, _3) with:

• A body containing two variables: {{1}} = customer first name, {{2}} = cart total
• A URL action button with a {{1}} variable at the end of the URL, pointing to https://your-site.com/wp-json/dfwc/v1/recover/{{1}}

Create each template in your customers’ languages: the plugin detects the locale and sends the right version. Once the templates are approved by Meta, enter their names in the plugin Settings.

The WhatsApp → Abandoned carts page shows the total, carts currently in reminders, recovered carts and the recovery rate.

Module 4 — Payment and notifications

The payment link generated in the conversation is an HMAC-signed token (SHA-256, WordPress salt + plugin secret) containing the cart, the expiry and the conversation ID. When the customer clicks:

1. The token is validated and decoded.
2. The WooCommerce cart is rebuilt server-side.
3. The customer’s phone is pre-filled at checkout.
4. The URL is cleaned by redirect.

Link validity is configurable (Settings → Payment). An expired link shows an error message inviting the customer to request a new one via WhatsApp.

Automatic notifications (individually togglable):

• Order confirmed — sent on transition to Processing, with number and total.
• Order shipped — sent on transition to Completed, with the tracking number detected from Shipment Tracking, AfterShip or the _tracking_number meta, and a tracking CTA button.
• Payment failed — sent on transition to Failed, with a retry-payment button.

Floating button and CTAs

• Floating button — togglable in Settings, position in any of the 4 corners, custom label, hideable. The templates/frontend/whatsapp-button.php template can be overridden by copying it to your-theme/dfwhatsappcommerce/whatsapp-button.php.
• Product page CTA — an “Order via WhatsApp” button under the add-to-cart button, with the product name and link pre-filled.
• Cart CTA — a “Complete via WhatsApp” button with the cart total.
• Checkout CTA — a discreet help link.
• Shortcode — [dfwc_whatsapp_button text="..." message="..."] for manual placement anywhere.

Clicks on all these elements are pushed to the dataLayer (prefix dfwc_) for GA4 / Google Tag Manager.

Logs and troubleshooting

The WhatsApp → Logs page shows all events with level filters (debug → critical) and channel filters (api, webhook, catalog, conversation, cart, payment). Log level and retention are configurable. Logs are also visible in WooCommerce → Status → Logs under the dfwhatsappcommerce-* sources.

Common issues:

• Webhook fails verification — make sure your site is served over HTTPS with a valid certificate, permalinks are not set to “Plain”, and the Verify Token pasted at Meta matches the one in Settings.
• Incoming messages never arrive — check that the messages field is subscribed in the Meta webhook configuration, and that the App Secret is correct (an invalid signature silently rejects requests — visible in the Logs, webhook channel).
• Catalog sync fails — make sure the system token has the catalog_management permission and the Catalog ID matches the catalog linked to your WhatsApp Business account.
• Reminders never fire — check that WordPress cron is running (WP Crontrol can show dfwc_process_abandoned_carts), and that the HSM templates are approved by Meta.

Uninstall

Deactivating the plugin keeps all data. Deleting it from the Plugins page triggers uninstall.php: the 5 tables are dropped, options and cron events removed. WooCommerce orders created via WhatsApp are never touched.