SW Shopware 6 Shopware Intermediate

WhatsApp Commerce Suite Shopware — Installation and configuration guide

Install the plugin, connect the Meta Cloud API, configure the webhook, HSM templates and the 4 modules on Shopware 6.5, 6.6 and 6.7.

Updated Module version 1.0.0

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

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.

Was this page helpful?

Still stuck? Contact support