# WhatsApp Commerce Suite Shopware — Installation and configuration guide
> Requirements Shopware 6.5, 6.6 or 6.7 (single codebase), PHP 8.1 minimum A WhatsApp Business account with a verified number in Meta Business Suite A Meta app of type Business with…
- Page:
- Language: en
- Last updated: 2026-08-06
- Other languages: [fr](https://www.datafirefly.com/documentation/dfwhatsappcommerce-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsappcommerce-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsappcommerce-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dfwhatsappcommerce-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwhatsappcommerce-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsappcommerce-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwhatsappcommerce-shopware/index.md)
- Index:
## Requirements
- Shopware 6.5, 6.6 or 6.7 (single codebase), PHP 8.1 minimum
- A **WhatsApp Business** account with a verified number in Meta Business Suite
- A Meta app of type **Business** with the WhatsApp product enabled
- The Shopware queue worker and scheduled task runner active (`messenger:consume` and `scheduled-task:run`)
## Installation
1. Copy the `DfWhatsAppCommerce` folder into `custom/plugins/` (or upload the zip via Extensions → My extensions).
2. Install and activate: ``` bin/console plugin:refresh bin/console plugin:install --activate DfWhatsAppCommerce bin/console cache:clear ```
3. Build the administration and the storefront: ``` bin/build-administration.sh bin/build-storefront.sh ```
Installation creates 5 dedicated tables prefixed `df_wac_` and 2 scheduled tasks (cart reminders every 15 min, hourly catalog batch). Everything is cleanly removed on uninstall, unless you tick "keep user data".
## Meta Cloud API setup
### 1. Collect the credentials
On [developers.facebook.com](https://developers.facebook.com), create a Business app and add the WhatsApp product. Collect: the **permanent token** (system user with `whatsapp_business_messaging` and `catalog_management` permissions), the **Phone number ID**, the **WABA ID** and the **App secret** (App settings → Basic).
### 2. Create the catalog
In Meta Commerce Manager, create a catalog and connect it to your WhatsApp Business account. Note the **catalog ID**.
### 3. Configure the webhook
In the Meta app → WhatsApp → Configuration:
- Callback URL: `https://yourshop.tld/df-wac/webhook`
- Verify token: the value you enter in the plugin config ("Webhook verify token" field)
- Subscribe to the `messages` field
Enter the **App secret** in the plugin configuration: without it, the `X-Hub-Signature-256` webhook signature is not validated.
### 4. Enter the configuration in Shopware
Settings → System → Plugins → DataFirefly WhatsApp Commerce Suite. Fill in the "Meta Cloud API" card, then test from the dashboard (Marketing → WhatsApp Commerce): **Test API connection** button and test message sending.
## The 4 modules
### Meta catalog
Three modes: real time (on every product save), hourly batch, or manual. Variants are sent individually with the `retailer_id` `sw_{product number}`. Exclude categories if needed. The full resync (batches of 100) is triggered from the dashboard.
### Conversational ordering
6-level state machine. Recognised keywords (FR/EN/DE): `menu`, `cart`, `pay`, `human`, `reset`, `help`. The customer's language is detected automatically. Human handoff sends an e-mail to the configured address with the conversation link.
### Abandoned cart recovery
3 configurable reminders (60 min, 24 h, 72 h by default) sent by the scheduled task every 15 minutes, to customers whose billing phone is known. The promo code entered in the config is attached to the 3rd reminder and applied automatically to the restored cart.
Make the phone field mandatory in Settings → Shop → Log-in / sign-up to maximise reminder coverage.
### Signed checkout link & notifications
Checkout and cart recovery links are HMAC SHA-256 signed with configurable expiry (72 h by default). Automatic notifications: order confirmation, shipping (with tracking number), payment failure.
## HSM templates to create in Meta Business Suite
| Template | Body variables | Button |
| --- | --- | --- |
| Reminder 1 & 2 | {{1}} customer name, {{2}} cart total | Dynamic URL (suffix = token) |
| Reminder 3 | {{1}} name, {{2}} total, {{3}} promo code | Dynamic URL (suffix = token) |
| Confirmation | {{1}} name, {{2}} order number, {{3}} total | — |
| Shipping | {{1}} name, {{2}} order number, {{3}} tracking number | Tracking CTA (optional) |
| Payment failed | {{1}} name, {{2}} order number | Retry CTA (optional) |
For reminders, the template's URL button must use the base `https://yourshop.tld/df-wac/cart/restore?token=` with dynamic suffix `{{1}}`. Enter the approved template names in the plugin configuration.
## Administration
Marketing → WhatsApp Commerce: KPI dashboard (conversations, unread, carts, recovery rate, errors), **Conversations** page (WhatsApp Web-style thread, direct reply), **Abandoned carts**, **Catalog** (sync log) and **Logs** (level/channel filters).
Meta rule: free-form replies from the admin are only delivered within 24 h of the customer's last message. Beyond that, use an HSM template.
## Troubleshooting
- **Nothing shows on the storefront**: check that the "Public WhatsApp number" is set (the floating button and CTAs depend on it), then `bin/console cache:clear`.
- **Webhook 403**: verify token mismatch between Meta and the plugin, or wrong App secret.
- **Reminders not sent**: check that `scheduled-task:run` and `messenger:consume` are running, the module is enabled and the HSM templates are approved.
- **Products not synced**: check the Catalog page (pending/synced/error statuses) and the Logs, channel `catalog`.
## GDPR
No data is sent to third parties other than the Meta WhatsApp Cloud API. Conversations and phone numbers are stored locally in the `df_wac_` tables and removed on uninstall.