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

- Seite: <https://www.datafirefly.com/de/documentation/dfwhatsapp/>
- Sprache: de
- Aktualisiert am: 2026-07-02
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfwhatsapp/index.md), [en](https://www.datafirefly.com/en/documentation/dfwhatsapp/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsapp/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwhatsapp/index.md), [it](https://www.datafirefly.com/it/documentation/dfwhatsapp/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsapp/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwhatsapp/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

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

**Tipp:** Das Modul erstellt automatisch 6 Tabellen in Ihrer Datenbank und fügt zwei Menüeinträge unter **Verkaufen > Katalog** für die Agentenverwaltung und das Analytics-Dashboard hinzu.

## 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")

**Hinweis:** Sie können auch _globale_ Ausnahmen hinzufügen, die für alle Agenten gelten, indem Sie die Agent-ID in der Datenbank auf 0 lassen.

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

**DSGVO-Konformität:**

- Ausdrückliche Einwilligung vor jedem WhatsApp-Öffnen angezeigt
- Besucher-IPs mit **SHA-256** gehasht unter Verwendung eines shop-spezifischen Salts (`PS_SHOP_DOMAIN` + `_COOKIE_KEY_`)
- Keine direkten personenbezogenen Daten gespeichert
- Keine Drittanbieter-Cookies gesetzt

## 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](mailto: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+