WhatsApp Commerce Suite — Installations- und Konfigurationsanleitung

Überblick

DataFirefly WhatsApp Commerce Suite macht WhatsApp zu einem vollständigen Vertriebskanal für WooCommerce — über die offizielle Cloud API von Meta. Das Plugin umfasst 4 unabhängig aktivierbare Module: Meta-Commerce-Katalog-Synchronisation, konversationelle Bestellannahme, Warenkorbabbruch-Rückgewinnung und signierter Zahlungslink.

Installation

1. Laden Sie dfwhatsappcommerce-1.0.0.zip aus Ihrem DataFirefly-Kundenkonto herunter.
2. Gehen Sie in wp-admin zu Plugins → Installieren → Plugin hochladen, wählen Sie das ZIP und klicken Sie auf Jetzt installieren.
3. Aktivieren Sie das Plugin. Ein neues Menü WhatsApp erscheint in der Admin-Seitenleiste.

Bei der Aktivierung erstellt das Plugin 5 SQL-Tabellen mit dem Präfix dfwc_ (Gespräche, Nachrichten, verlassene Warenkörbe, Katalog-Log, Protokolle) und plant 3 Cron-Ereignisse: Warenkorb-Verarbeitung alle 15 Minuten, tägliche Log-Bereinigung und stündliche Batch-Katalog-Synchronisation.

Voraussetzungen auf Meta-Seite

Sammeln Sie vor der Konfiguration diese 5 Werte aus der Meta Business Suite:

• Phone Number ID — WhatsApp → API-Einrichtung → Ihre Nummer
• WhatsApp Business Account ID — sichtbar in den Einstellungen Ihres WhatsApp-Business-Kontos
• Catalog ID — Commerce Manager → Ihr Katalog → Einstellungen
• Permanenter Access Token — erstellen Sie einen Systembenutzer unter Business Settings → Users → System Users, weisen Sie ihm die Berechtigungen whatsapp_business_messaging, whatsapp_business_management und catalog_management zu und generieren Sie dann ein Token ohne Ablaufdatum
• App Secret — Meta for Developers → Ihre App → Einstellungen → Allgemein

Plugin-Konfiguration

1. Gehen Sie zu WhatsApp → Einstellungen.
2. Fügen Sie im Abschnitt Meta-Cloud-API-Zugangsdaten die 5 oben gesammelten Werte ein. Das Feld Webhook Verify Token wird automatisch vorgeneriert — ändern Sie es nur bei Bedarf.
3. Tragen Sie die angezeigte WhatsApp-Nummer im E.164-Format ohne + ein (Beispiel: 4915112345678). Diese Nummer steuert die schwebende Schaltfläche und die CTAs.
4. Aktivieren Sie die gewünschten Module im Abschnitt Module. Sie können mit der Katalog-Synchronisation allein beginnen und den Rest schrittweise aktivieren.
5. Speichern.

Konfiguration des Meta-Webhooks

Über den Webhook liefert Meta eingehende Nachrichten und Zustellstatus an Ihre Website.

1. Öffnen Sie WhatsApp → Übersicht in wp-admin: die Callback URL und das Verify Token werden dort mit Kopieren-Schaltflächen angezeigt.
2. Öffnen Sie in Meta for Developers Ihre App → WhatsApp → Konfiguration → Webhook.
3. Fügen Sie Callback URL und Verify Token ein und klicken Sie auf Verifizieren und speichern.
4. Abonnieren Sie in der Feldliste das Feld messages.

Die Callback URL hat die Form https://ihre-website.de/wp-json/dfwc/v1/webhook. Jede eingehende Anfrage wird per HMAC-SHA-256-Signatur gegen Ihr App Secret validiert: unsignierte oder falsch signierte Anfragen werden abgelehnt.

Verbindungstest

Von WhatsApp → Übersicht aus:

• API-Verbindung testen — prüft Ihre Zugangsdaten durch Abfrage Ihrer Phone Number ID und zeigt die verifizierte Nummer.
• Testnachricht senden — geben Sie eine Nummer im E.164-Format ohne + ein und senden Sie eine Test-Textnachricht.

Modul 1 — Katalog-Synchronisation

Drei Modi in den Einstellungen verfügbar:

• Echtzeit — jede Produkterstellung, Änderung, Bestandsänderung oder Löschung wird sofort im Meta-Katalog abgebildet.
• Stapelweise — Änderungen werden gesammelt und stündlich in Stapeln von 50 übertragen.
• Manuell — nichts wird automatisch gesendet; Sie verwenden die Resync-Schaltfläche.

Mapping-Regeln:

• Jedes Produkt erhält eine retailer_id der Form wc_{ID}.
• Variable Produkte werden nicht als solche gesendet: jede Variation wird einzeln mit eigenem Preis, Bestand und Bild übertragen.
• Produkte ohne Bild werden übersprungen (Meta-Anforderung).
• Der Filter dfwc_catalog_product_eligible erlaubt den Ausschluss von Produkten per Code, dfwc_catalog_product_data die Anpassung der gesendeten Daten.

Die Seite WhatsApp → Katalog zeigt Erfolgs- und Fehlerzähler, das Log der letzten 50 Ereignisse und die Schaltfläche Resync starten, die alle berechtigten Produkte in Stapeln von 100 erneut überträgt.

Modul 2 — Konversationelle Bestellung

Das Gesprächsmodul antwortet automatisch auf eingehende Nachrichten anhand einer Zustandsmaschine: idle → browsing → selecting_qty → reviewing → awaiting_payment, plus ein Zustand human_handoff.

Erkannte Schlüsselwörter (Französisch und Englisch im selben Gespräch):

• menu oder catalogue — zeigt die interaktive Produktliste (bis zu 30 Elemente, verbunden mit dem Meta-Katalog)
• cart oder panier — zeigt den Warenkorbinhalt mit den Schaltflächen Bezahlen / Weiter / Leeren
• checkout, pay oder payer — erzeugt den Zahlungslink
• human, humain oder aide — übergibt an einen Berater (E-Mail an die konfigurierte Adresse)
• reset oder annuler — setzt das Gespräch zurück

Jeder andere Text löst eine Volltextsuche in Ihren Produkten aus. Der Warenkorb des Kunden bleibt im Gespräch erhalten und wird mit seinem WooCommerce-Konto verknüpft, wenn seine Nummer einem vorhandenen billing_phone entspricht.

Willkommens- und Fallback-Nachricht sind in den Einstellungen anpassbar. Die Seite WhatsApp → Gespräche listet alle Gespräche und zeigt jeden Thread in einer WhatsApp-Web-artigen Ansicht.

Modul 3 — Warenkorbabbruch-Rückgewinnung

Funktionsweise:

1. Das Plugin erfasst die Warenkörbe der Besucher (WooCommerce-Session + 7-Tage-Fallback-Cookie) und macht das Telefonfeld im Checkout zur Pflicht.
2. Nach der Abbruchschwelle (60 Minuten Standard) wird die erste Erinnerung gesendet. Erinnerung 2 und 3 folgen ihren eigenen Verzögerungen (24 Std. und 72 Std. Standard, in Minuten in den Einstellungen).
3. Jede Erinnerung verwendet ein pro Stufe konfiguriertes Meta-HSM-Template. Schlägt das Template fehl, wird eine einfache Textnachricht als Fallback versucht.
4. Die dritte Erinnerung kann einen vorhandenen WooCommerce-Gutscheincode beifügen, der über den Wiederherstellungslink automatisch im Checkout angewendet wird.
5. Schließt der Kunde seine Bestellung ab, wird der Warenkorb als wiedergewonnen markiert und die Erinnerungen stoppen.

Erstellung der HSM-Templates

Erstellen Sie in Meta Business Suite → WhatsApp Manager → Nachrichtenvorlagen 3 Templates (z. B. dfwc_abandoned_cart_1, _2, _3) mit:

• Einem Text mit zwei Variablen: {{1}} = Vorname des Kunden, {{2}} = Warenkorbbetrag
• Einer URL-Aktionsschaltfläche mit einer Variable {{1}} am Ende der URL, die auf https://ihre-website.de/wp-json/dfwc/v1/recover/{{1}} zeigt

Erstellen Sie jedes Template in den Sprachen Ihrer Kunden: das Plugin erkennt die Locale und sendet die richtige Version. Sobald die Templates von Meta genehmigt sind, tragen Sie ihre Namen in den Plugin-Einstellungen ein.

Die Seite WhatsApp → Verlassene Warenkörbe zeigt Gesamtzahl, Warenkörbe in Erinnerung, wiedergewonnene Warenkörbe und die Rückgewinnungsquote.

Modul 4 — Zahlung und Benachrichtigungen

Der im Gespräch erzeugte Zahlungslink ist ein HMAC-signiertes Token (SHA-256, WordPress-Salt + Plugin-Geheimnis) mit Warenkorb, Ablaufdatum und Gesprächs-ID. Beim Klick des Kunden:

1. Das Token wird validiert und dekodiert.
2. Der WooCommerce-Warenkorb wird serverseitig neu aufgebaut.
3. Die Telefonnummer des Kunden wird im Checkout vorausgefüllt.
4. Die URL wird per Weiterleitung bereinigt.

Die Gültigkeit des Links ist konfigurierbar (Einstellungen → Zahlung). Ein abgelaufener Link zeigt eine Fehlermeldung mit der Aufforderung, über WhatsApp einen neuen anzufordern.

Automatische Benachrichtigungen (einzeln aktivierbar):

• Bestellung bestätigt — gesendet beim Übergang zu Processing, mit Nummer und Gesamtbetrag.
• Bestellung versandt — gesendet beim Übergang zu Completed, mit der Sendungsnummer aus Shipment Tracking, AfterShip oder der Meta _tracking_number, plus Tracking-CTA-Schaltfläche.
• Zahlung fehlgeschlagen — gesendet beim Übergang zu Failed, mit einer Schaltfläche zur Zahlungswiederholung.

Schwebende Schaltfläche und CTAs

• Schwebende Schaltfläche — in den Einstellungen aktivierbar, Position in einer der 4 Ecken, anpassbares Label, ausblendbar. Das Template templates/frontend/whatsapp-button.php kann überschrieben werden, indem Sie es nach ihr-theme/dfwhatsappcommerce/whatsapp-button.php kopieren.
• Produktseiten-CTA — Schaltfläche „Über WhatsApp bestellen“ unter dem Warenkorb-Button, mit vorausgefülltem Produktnamen und Link.
• Warenkorb-CTA — Schaltfläche „Über WhatsApp abschließen“ mit dem Warenkorbbetrag.
• Checkout-CTA — dezenter Hilfe-Link.
• Shortcode — [dfwc_whatsapp_button text="..." message="..."] für manuelle Platzierung an beliebiger Stelle.

Klicks auf alle diese Elemente werden in den dataLayer gepusht (Präfix dfwc_) für GA4 / Google Tag Manager.

Protokolle und Fehlerbehebung

Die Seite WhatsApp → Protokolle zeigt alle Ereignisse mit Filtern nach Level (debug → critical) und Kanal (api, webhook, catalog, conversation, cart, payment). Log-Level und Aufbewahrung sind konfigurierbar. Die Logs sind auch unter WooCommerce → Status → Protokolle unter den Quellen dfwhatsappcommerce-* sichtbar.

Häufige Probleme:

• Webhook-Verifizierung schlägt fehl — stellen Sie sicher, dass Ihre Website über HTTPS mit gültigem Zertifikat erreichbar ist, die Permalinks nicht auf „Einfach“ stehen und das bei Meta eingefügte Verify Token mit dem in den Einstellungen übereinstimmt.
• Eingehende Nachrichten kommen nicht an — prüfen Sie, ob das Feld messages in der Meta-Webhook-Konfiguration abonniert ist und das App Secret korrekt ist (eine ungültige Signatur lehnt Anfragen stillschweigend ab — sichtbar in den Protokollen, Kanal webhook).
• Katalog-Synchronisation schlägt fehl — stellen Sie sicher, dass das Systemtoken die Berechtigung catalog_management besitzt und die Catalog ID dem mit Ihrem WhatsApp-Business-Konto verknüpften Katalog entspricht.
• Erinnerungen werden nicht gesendet — prüfen Sie, ob der WordPress-Cron läuft (WP Crontrol zeigt dfwc_process_abandoned_carts) und die HSM-Templates von Meta genehmigt sind.

Deinstallation

Die Deaktivierung des Plugins behält alle Daten. Das endgültige Löschen über die Plugin-Seite löst uninstall.php aus: die 5 Tabellen werden gelöscht, Optionen und Cron-Ereignisse entfernt. Über WhatsApp erstellte WooCommerce-Bestellungen werden niemals angetastet.