# 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,…

- Page: <https://www.datafirefly.com/en/documentation/dfwhatsappcommerce/>
- Language: en
- Last updated: 2026-09-01
- Other languages: [fr](https://www.datafirefly.com/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/en/documentation/llms.txt>

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

Requirements: WordPress 6.2+, WooCommerce 8.0+, PHP 7.4+, a WhatsApp Business account with a verified number in Meta Business Suite, and a site served over HTTPS (mandatory for the Meta webhook).

## Installation

1. Download `dfwhatsappcommerce-1.0.1.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](https://business.facebook.com):

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

Never use the temporary 24-hour token shown on the Getting Started tab: it will expire and break the sync. Always create a permanent system-user token.

## 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](https://developers.facebook.com), 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.

If the test message never arrives even though the connection is OK, check that the recipient has messaged your WhatsApp Business number in the last 24h, or use an approved HSM template: Meta only allows free-form text messages inside the 24-hour service window.

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

Since version 1.0.1, **Settings → Catalog sync** offers two category lists: **Categories to sync** (leave empty to send everything) and **Categories to exclude**. Products without an image are logged with the `skipped` status instead of being re-selected on every batch. In real-time mode, every sync is queued through Action Scheduler (bundled with WooCommerce): saving a product or reducing stock on each order never waits for Meta's reply. You can follow these jobs under **WooCommerce → Status → Scheduled Actions**, group `dfwhatsappcommerce`.

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.

Meta only accepts free-form text within 24 hours of the customer's last message. An order placed by a customer who never wrote on WhatsApp, or did so more than 24 hours ago, can only be notified with an approved HSM template. Fill in the three optional templates under **Settings → Payment**: **order confirmation** (variables {{1}} number, {{2}} total), **shipping** ({{1}} number, {{2}} tracking number) and **payment failed** ({{1}} number, {{2}} payment link). Without a template the plugin sends free-form text, which only gets through inside the 24-hour window. The shipping notification is sent once per tracking number, and orders with nothing to ship get a confirmation instead of an "on its way" message.

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