SW Shopware 6 Shopware Mittel

WhatsApp Commerce Suite Shopware — Installations- und Konfigurationsanleitung

Plugin installieren, Meta Cloud API verbinden, Webhook, HSM-Templates und die 4 Module auf Shopware 6.5, 6.6 und 6.7 konfigurieren.

Aktualisiert Modulversion 1.0.0

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

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.

War diese Seite hilfreich?

Immer noch nicht weiter? Support kontaktieren