# WhatsApp Commerce Suite Shopware — Installations- und Konfigurationsanleitung > Voraussetzungen Shopware 6.5, 6.6 oder 6.7 (eine Codebasis), PHP 8.1 Minimum Ein WhatsApp-Business-Konto mit verifizierter Nummer in der Meta Business Suite Eine Meta-App vom Typ Business mit aktiviertem WhatsApp-Produkt Aktiver… - Seite: - Sprache: de - Aktualisiert am: 2026-08-06 - Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfwhatsappcommerce-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/dfwhatsappcommerce-shopware/index.md), [es](https://www.datafirefly.com/es/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: ## Voraussetzungen - Shopware 6.5, 6.6 oder 6.7 (eine Codebasis), PHP 8.1 Minimum - Ein **WhatsApp-Business**-Konto mit verifizierter Nummer in der Meta Business Suite - Eine Meta-App vom Typ **Business** mit aktiviertem WhatsApp-Produkt - Aktiver Shopware Queue-Worker und Scheduled-Task-Runner (`messenger:consume` und `scheduled-task:run`) ## Installation 1. Kopieren Sie den Ordner `DfWhatsAppCommerce` nach `custom/plugins/` (oder laden Sie das Zip über Erweiterungen → Meine Erweiterungen hoch). 2. Installieren und aktivieren: ``` bin/console plugin:refresh bin/console plugin:install --activate DfWhatsAppCommerce bin/console cache:clear ``` 3. Administration und Storefront kompilieren: ``` bin/build-administration.sh bin/build-storefront.sh ``` Die Installation erstellt 5 dedizierte Tabellen mit dem Präfix `df_wac_` sowie 2 geplante Aufgaben (Warenkorb-Erinnerungen alle 15 Min., stündlicher Katalog-Batch). Bei der Deinstallation wird alles sauber entfernt, sofern Sie nicht „Daten behalten" wählen. ## Meta Cloud API Einrichtung ### 1. Zugangsdaten beschaffen Erstellen Sie auf [developers.facebook.com](https://developers.facebook.com) eine Business-App und fügen Sie das WhatsApp-Produkt hinzu. Beschaffen Sie: den **permanenten Token** (Systembenutzer mit den Berechtigungen `whatsapp_business_messaging` und `catalog_management`), die **Phone number ID**, die **WABA-ID** und das **App-Secret** (App-Einstellungen → Allgemein). ### 2. Katalog erstellen Erstellen Sie im Meta Commerce Manager einen Katalog und verbinden Sie ihn mit Ihrem WhatsApp-Business-Konto. Notieren Sie die **Katalog-ID**. ### 3. Webhook konfigurieren In der Meta-App → WhatsApp → Konfiguration: - Callback-URL: `https://ihrshop.tld/df-wac/webhook` - Verifizierungstoken: der Wert, den Sie in der Plugin-Konfiguration eintragen (Feld „Webhook verify token") - Abonnieren Sie das Feld `messages` Tragen Sie das **App-Secret** in der Plugin-Konfiguration ein: ohne dieses wird die `X-Hub-Signature-256`-Signatur der Webhooks nicht validiert. ### 4. Konfiguration in Shopware eintragen Einstellungen → System → Plugins → DataFirefly WhatsApp Commerce Suite. Füllen Sie die Karte „Meta Cloud API" aus und testen Sie über das Dashboard (Marketing → WhatsApp Commerce): Button **API-Verbindung testen** und Versand einer Testnachricht. ## Die 4 Module ### Meta-Katalog Drei Modi: Echtzeit (bei jedem Produktspeichern), stündlicher Batch oder manuell. Varianten werden einzeln mit der `retailer_id` `sw_{Artikelnummer}` gesendet. Schließen Sie bei Bedarf Kategorien aus. Die vollständige Resynchronisation (Batches von 100) starten Sie über das Dashboard. ### Bestellung im Chat 6-stufige State Machine. Erkannte Schlüsselwörter (FR/EN/DE): `menü`, `warenkorb`, `bezahlen`, `mensch`, `neustart`, `hilfe`. Die Sprache des Kunden wird automatisch erkannt. Die menschliche Übergabe sendet eine E-Mail an die konfigurierte Adresse mit dem Link zur Unterhaltung. ### Warenkorb-Wiederherstellung 3 konfigurierbare Erinnerungen (standardmäßig 60 Min., 24 h, 72 h), versendet durch die geplante Aufgabe alle 15 Minuten an Kunden mit bekannter Rechnungstelefonnummer. Der in der Konfiguration eingetragene Gutscheincode wird der 3. Erinnerung beigefügt und automatisch auf den wiederhergestellten Warenkorb angewendet. Machen Sie das Telefonfeld unter Einstellungen → Shop → Anmeldung / Registrierung zum Pflichtfeld, um die Abdeckung der Erinnerungen zu maximieren. ### Signierter Checkout-Link & Benachrichtigungen Checkout- und Wiederherstellungslinks sind HMAC-SHA-256-signiert mit konfigurierbarem Ablauf (standardmäßig 72 h). Automatische Benachrichtigungen: Bestellbestätigung, Versand (mit Sendungsnummer), Zahlungsfehler. ## In der Meta Business Suite zu erstellende HSM-Templates | Template | Body-Variablen | Button | | --- | --- | --- | | Erinnerung 1 & 2 | {{1}} Kundenname, {{2}} Warenkorbsumme | Dynamische URL (Suffix = Token) | | Erinnerung 3 | {{1}} Name, {{2}} Summe, {{3}} Gutscheincode | Dynamische URL (Suffix = Token) | | Bestätigung | {{1}} Name, {{2}} Bestellnummer, {{3}} Summe | — | | Versand | {{1}} Name, {{2}} Bestellnummer, {{3}} Sendungsnummer | Tracking-CTA (optional) | | Zahlungsfehler | {{1}} Name, {{2}} Bestellnummer | Retry-CTA (optional) | Für die Erinnerungen muss der URL-Button des Templates die Basis `https://ihrshop.tld/df-wac/cart/restore?token=` mit dynamischem Suffix `{{1}}` verwenden. Tragen Sie die Namen der genehmigten Templates in der Plugin-Konfiguration ein. ## Administration Marketing → WhatsApp Commerce: KPI-Dashboard (Unterhaltungen, Ungelesene, Warenkörbe, Wiederherstellungsquote, Fehler), Seite **Unterhaltungen** (Thread im WhatsApp-Web-Stil, Direktantwort), **Verlassene Warenkörbe**, **Katalog** (Sync-Protokoll) und **Protokolle** (Filter nach Level/Kanal). Meta-Regel: Freitextantworten aus dem Admin werden nur innerhalb von 24 h nach der letzten Kundennachricht zugestellt. Danach verwenden Sie ein HSM-Template. ## Fehlerbehebung - **Im Storefront erscheint nichts**: Prüfen Sie, ob die „Öffentliche WhatsApp-Nummer" eingetragen ist (der schwebende Button und die CTAs hängen davon ab), dann `bin/console cache:clear`. - **Webhook 403**: Verifizierungstoken zwischen Meta und Plugin unterschiedlich, oder falsches App-Secret. - **Erinnerungen werden nicht gesendet**: Prüfen Sie, ob `scheduled-task:run` und `messenger:consume` laufen, das Modul aktiv ist und die HSM-Templates genehmigt sind. - **Produkte nicht synchronisiert**: Prüfen Sie die Katalog-Seite (Status pending/synced/error) und die Protokolle, Kanal `catalog`. ## DSGVO Außer an die Meta WhatsApp Cloud API werden keine Daten an Dritte gesendet. Unterhaltungen und Nummern werden lokal in den `df_wac_`-Tabellen gespeichert und bei der Deinstallation entfernt.