DataFirefly WhatsApp — Dokumentation

Willkommen zur Dokumentation des DataFirefly WhatsApp-Moduls. Dieser Leitfaden deckt alles ab, was Sie brauchen, um Ihren schwebenden Multi-Agent-WhatsApp-Button auf PrestaShop 8 und 9 zu installieren, konfigurieren und optimal zu nutzen.

Installation

Das Modul wird wie jedes andere PrestaShop-Modul mit wenigen Klicks installiert.

Voraussetzungen

• PrestaShop 8.0.x oder 9.0.x
• PHP 8.0 oder höher (8.1+ empfohlen)
• MySQL 5.6+ oder MariaDB 10.3+
• Mindestens eine WhatsApp-Nummer (privat oder Business)

Installationsschritte

1. Laden Sie die Datei dfwhatsapp-v1.0.0.zip aus Ihrem DataFirefly-Kundenbereich herunter
2. Gehen Sie im PrestaShop-Backoffice zu Module > Modul-Manager
3. Klicken Sie oben rechts auf Modul hochladen
4. Wählen Sie die ZIP-Datei und bestätigen Sie
5. Klicken Sie auf Installieren, sobald das Modul erscheint
6. Klicken Sie auf Konfigurieren, um den Einstellungsbildschirm zu öffnen

Allgemeine Konfiguration

Die Konfigurationsseite des Moduls ist in 6 Tabs unterteilt, damit Sie alles einstellen können, ohne den Überblick zu verlieren.

Tab Allgemein

• Modul aktivieren: Hauptschalter, deaktiviert den Button im gesamten Shop
• Agentenauswahl-Modus: Round-Robin, Zufall, erster verfügbarer, oder manuell
• Tracking aktivieren: erforderlich, um das Analytics-Dashboard zu füttern
• Desktop-QR-Code: zeigt einen QR-Code an, statt WhatsApp Web auf dem Desktop zu öffnen

Tab Aussehen

• Position: vier mögliche Ecken (unten-rechts, unten-links, oben-rechts, oben-links)
• Farbe: standardmäßig WhatsApp-Grün #25D366
• Icon-Größe: in Pixeln (Standard 60)
• X / Y-Versatz: Abstand vom Bildschirmrand
• Animation: pulse, bounce, shake oder keine
• Textlabel: optionales Label neben dem Button

Tab Nachrichten

Eine eigene vorgefüllte Nachricht für jeden Seitentyp (Produkt, Warenkorb, Kategorie, CMS, Bestellung, Startseite), übersetzt in alle 4 mitgelieferten Sprachen.

Tab Zeitplan

• Modus außerhalb der Öffnungszeiten:
  • hide — der Button verschwindet komplett
  • show_offline — der Button bleibt ausgegraut sichtbar mit einer Wartemeldung
  • callback — ein Rückruf-Formular ersetzt das direkte Gespräch
• Meldung außerhalb der Öffnungszeiten: Text, der angezeigt wird, wenn alle Agenten offline sind

Tab DSGVO

• Einwilligung aktivieren: zeigt vor jedem WhatsApp-Öffnen einen Einwilligungstext an
• Einwilligungstext: pro Sprache anpassbar

Tab Ausschlüsse

• Ausgeschlossene Seiten: Liste der Controller (z. B. checkout, identity)
• Ausgeschlossene Kategorien: Kategorie-IDs durch Kommas getrennt
• Ausgeschlossene Produkte: Produkt-IDs durch Kommas getrennt

Agentenverwaltung

Das Herzstück des Moduls: Hier fügen Sie die Personen hinzu, die WhatsApp-Nachrichten empfangen werden.

Einen Agenten hinzufügen

1. Gehen Sie zu Verkaufen > Katalog > WhatsApp-Agenten
2. Klicken Sie auf Hinzufügen
3. Füllen Sie aus:
   • Name — dem Kunden angezeigter Name (z. B. „Alex“)
   • Telefon — internationales Format ohne Leerzeichen (z. B. 33604525981)
   • Abteilung — Freitext (Support, Vertrieb, Technik…)
   • Avatar — optionales Bild (png, jpg, svg, webp)
   • Position — Anzeigereihenfolge im manuellen Modus
   • Rolle — Text übersetzt in 4 Sprachen (z. B. „Technischer Support“)
   • Benutzerdefinierte Nachricht — optionales Überschreiben der kontextuellen Nachrichten

Öffnungszeiten eines Agenten konfigurieren

Direkt im Agentenformular können Sie in einer Wochentabelle festlegen:

• Mehrere Zeitfenster pro Tag (z. B. 9:00-12:30 + 14:00-18:30)
• Ein leerer Tag = Agent an diesem Tag offline
• Ein Agent ohne definiertes Zeitfenster gilt als immer online (24/7-Modus)

Eine Ausnahme hinzufügen (Feiertag, Urlaub)

1. Im Agentenformular, Bereich Ausnahmen
2. Geben Sie ein Startdatum und ein Enddatum ein
3. Fügen Sie ein optionales Label hinzu (z. B. „Sommerurlaub“)

Kontextvariablen

Die vorgefüllten Nachrichten unterstützen 12 Variablen, die je nach Seite, auf der sich der Kunde befindet, spontan ersetzt werden:

• {product_name} — Produktname (Produktseite)
• {product_url} — vollständige Produkt-URL
• {product_price} — mit Währung formatierter Preis
• {product_ref} — Produktreferenz
• {customer_name} — Kundenname, wenn eingeloggt
• {cart_id} — Warenkorb-ID
• {cart_total} — formatierter Warenkorbwert
• {cart_summary} — Liste der Warenkorbartikel
• {order_ref} — Bestellreferenz
• {order_total} — Bestellsumme
• {category_name} — Name der aktuellen Kategorie
• {shop_name} — Shopname

Agenten-Routing-Modi

Round-Robin

Das Modul wechselt bei jeder neuen Öffnung zwischen den verfügbaren Agenten und gleicht so die Last natürlich aus.

Zufall

Ein Agent wird zufällig aus den Online-Agenten ausgewählt. Nützlich, wenn die Fairness zwischen den Agenten nicht kritisch ist.

Erster verfügbarer

Der erste Agent aus der Liste (nach Position), der aktuell online ist, wird ausgewählt.

Manuell

Dem Kunden erscheint ein Popup mit der Liste der verfügbaren Agenten (Avatar, Name, Rolle, Status). Der Kunde wählt seinen Gesprächspartner selbst aus.

Analytics und DSGVO

Das Dashboard

Zugänglich über Verkaufen > Katalog > WhatsApp Analytics, zeigt es Ihnen:

• Gesamtklicks im Zeitraum
• Anzahl eindeutiger Besucher (über IP-Hashing)
• Klicks pro Besucher-Verhältnis
• Aufschlüsselung nach Tag, Seitentyp, Agent
• Top 20 Produkte, die Gespräche auslösen

Datenschutz

QR-Code auf dem Desktop

Auf Desktop-Computern können Sie, anstatt WhatsApp Web zu öffnen (was systematisches QR-Code-Scannen durch den Kunden erfordert), den direkten QR-Code-Modus aktivieren:

• Das Modul generiert einen QR-Code, der den wa.me-Link mit der vorgefüllten Nachricht enthält
• Der Kunde scannt ihn mit seinem Telefon
• WhatsApp öffnet sich direkt auf seinem Mobilgerät mit der versandbereiten Nachricht

Dieser Modus hält das Gespräch ohne zusätzliche Reibung im bevorzugten Kanal des Kunden.

Rückruf-Formular

Wenn alle Ihre Agenten offline sind und Sie den callback-Modus gewählt haben:

1. Der Kunde sieht ein Formular statt des üblichen Gesprächs
2. Er gibt seinen Namen, seine Telefonnummer und eine optionale Nachricht ein
3. Die Anfrage wird in der Tabelle ps_dfwhatsapp_callback mit dem Status pending gespeichert
4. Sie können die Anfragen über phpMyAdmin einsehen oder einen benutzerdefinierten Bericht erstellen

Mehrsprachigkeit

Das Modul wird mit 4 vollständigen Sprachen ausgeliefert: Französisch, Englisch, Spanisch, Deutsch. Alle kundenseitig sichtbaren Texte sind übersetzt:

• Kontextuelle Nachrichten pro Seite
• DSGVO-Einwilligungstext
• Willkommens-Popup-Nachricht
• Agenten-Labels (Rolle, Status)
• Rückruf-Formular-Oberfläche
• Meldung außerhalb der Öffnungszeiten

Sie können auch eine unterschiedliche Rolle und benutzerdefinierte Nachricht für jede Sprache und jeden Agenten festlegen, direkt aus dem Agentenformular durch Wechsel des Sprach-Tabs.

Kompatibilität

• PrestaShop 8.0.x, 8.1.x, 8.2.x, 9.0.x
• PHP 8.0 bis 8.3
• Mehrere Shops ja (getrennte Konfigurationen pro Shop)
• Mehrsprachig ja (Polylang nicht erforderlich)
• Cache kompatibel (Hummingbird, LSCache, Redis)
• Core-Class-Override: keiner

Fehlerbehebung

Der Button erscheint nicht

1. Prüfen Sie, dass das Modul unter Allgemein aktiviert ist
2. Prüfen Sie, dass mindestens ein Agent mit Status Aktiv existiert
3. Prüfen Sie, dass die aktuelle Seite nicht in der Ausschlussliste steht
4. Leeren Sie den PrestaShop-Cache (Erweiterte Parameter > Performance)
5. Leeren Sie den Browser-Cache (Strg+Umschalt+R)

Der Klick auf den Button macht nichts

1. Öffnen Sie die Browser-Konsole (F12) und prüfen Sie, ob es JavaScript-Fehler gibt
2. Prüfen Sie, dass kein anderes Modul das JS des Moduls blockiert
3. Prüfen Sie, dass dfwhatsapp.js im HTML korrekt geladen wird

Die Statistiken erhöhen sich nicht

1. Prüfen Sie, dass Tracking unter Allgemein aktiviert ist
2. Prüfen Sie, dass kein clientseitiger Werbeblocker die URL module/dfwhatsapp/track filtert
3. Prüfen Sie die Tabelle ps_dfwhatsapp_click, um zu sehen, ob Ereignisse ankommen

SQL-Fehler „LIMIT 1 LIMIT 1″

Behoben in Version 1.0.1. Aktualisieren Sie Ihr Modul aus Ihrem DataFirefly-Kundenbereich auf die neueste Version.

Support und Updates

• E-Mail-Support: hello@datafirefly.com
• Updates 12 Monate lang aus Ihrem Kundenbereich enthalten
• PS 8 → 9 Kompatibilität ohne Aufpreis garantiert

Changelog

1.0.0 — 13. Mai 2026 — Launch

• Erste öffentliche Version
• Multi-Agent mit vier Routing-Modi
• Wöchentlicher Zeitplan pro Agent mit Ausnahmen
• Willkommens-Popup, Desktop-QR-Code, Rückruf-Formular
• Natives DSGVO-Einverständnis und Analytics mit gehashter IP
• Vier Sprachen: FR, EN, ES, DE
• Kompatibel mit PrestaShop 8.0+ und 9.0+