KI-Kundenservice-Agent — Vollständige Dokumentation

Vollständige Installations-, Konfigurations- und Nutzungsanleitung für das Plugin DataFirefly AI Customer Service Agent — ein KI-Kundenservice-Agent für WooCommerce, der Kontext versteht, schreibgeschützte Tools in Ihrem Shop aufruft und komplexe Fälle intelligent an Slack und E-Mail eskaliert.

1. Voraussetzungen

• WordPress 6.4 oder höher
• WooCommerce 8.0 oder höher
• PHP 8.1, 8.2 oder 8.3
• Ein API-Schlüssel von Anthropic (Claude) oder OpenAI (empfohlen: Claude Sonnet 4.5)
• Optional: ein Slack-Webhook für Echtzeit-Eskalation
• Optional: Polylang Pro oder WPML, falls Ihr Shop mehrsprachig ist

2. Installation

ZIP-Installation

1. Laden Sie in Ihrem DataFirefly-Konto die Datei df-ai-customer-service.zip herunter
2. Gehen Sie in WordPress zu Plugins → Installieren → Plugin hochladen
3. Wählen Sie das ZIP und klicken Sie auf Jetzt installieren
4. Klicken Sie nach abgeschlossener Installation auf Aktivieren

Was passiert bei der Aktivierung?

Das Plugin erstellt automatisch 5 Datenbanktabellen mit Präfix wp_dfaics_: conversations, messages, escalations, faq, analytics. Es deklariert außerdem die HPOS- und Gutenberg-Cart/Checkout-Blöcke-Kompatibilität und plant einen täglichen Cron-Job zur Bereinigung abgelaufener Konversationen.

3. Konfiguration des KI-Providers

Das Plugin unterstützt zwei KI-Provider. Sie wählen Ihren bevorzugten in AI Support → Einstellungen → KI. Sie bringen Ihren eigenen API-Schlüssel mit — DataFirefly proxyt nichts und nimmt keinen Anteil an Ihrem Verbrauch.

Option A: Claude (empfohlen)

1. Erstellen Sie ein Konto auf console.anthropic.com
2. Generieren Sie einen API-Schlüssel unter Settings → API Keys
3. Kopieren Sie den Schlüssel (beginnt mit sk-ant-...)
4. Gehen Sie in WordPress zu AI Support → Einstellungen → KI
5. Wählen Sie den Provider Anthropic (Claude)
6. Fügen Sie Ihren Schlüssel im Feld Anthropic-API-Schlüssel ein
7. Standardmodell: claude-sonnet-4-5 (hervorragendes Preis-Leistungs-Verhältnis)
8. Klicken Sie auf Schlüssel testen zur Validierung
9. Speichern

Option B: OpenAI

1. Erstellen Sie ein Konto auf platform.openai.com
2. Generieren Sie einen API-Schlüssel unter API Keys
3. Kopieren Sie den Schlüssel (beginnt mit sk-...)
4. Wählen Sie in WordPress den Provider OpenAI
5. Standardmodell: gpt-4o-mini (am wirtschaftlichsten mit zuverlässigem Tool Calling)

Richtwerte für Kosten

Eine typische Konversation mit 5 bis 10 Runden und Tool Calling kostet:

• Ungefähr 0,01 bis 0,05 USD mit Claude Sonnet 4.5
• Ungefähr 0,005 bis 0,02 USD mit GPT-4o mini

Das Dashboard zeigt die im Zeitraum verbrauchten Gesamt-Input/Output-Token.

4. Widget-Konfiguration

Das Chat-Widget erscheint standardmäßig unten rechts auf allen Frontend-Seiten. Passen Sie es in AI Support → Einstellungen → Widget an.

Erscheinungsoptionen

• Hauptfarbe — Farbe des Floating-Buttons und des Headers (Standard #0073aa)
• Textfarbe — Textfarbe im Header (Standard Weiß)
• Position — Unten rechts oder unten links
• Widget-Titel — z. B. „Brauchen Sie Hilfe?“
• Begrüßungsnachricht — Erste angezeigte Nachricht beim Öffnen
• Platzhalter — Text des Eingabefelds
• DataFirefly-Badge anzeigen — Kleiner Hinweis am Fuß des Widgets

Bedingte Anzeige

Im Tab Widget können Sie einschränken, wo das Widget angezeigt wird:

• Alle Seiten — Standardverhalten
• Nur Produktseiten — Für gezielten Support auf Produktseiten
• Außer Warenkorb und Checkout — Ablenkungen während des Kaufs vermeiden
• Auf diesen Inhalts-IDs ausblenden — Liste auszuschließender IDs

Shortcode

Sie können den Chat auch mit dem Shortcode in eine Seite oder einen Beitrag einbetten:

[dfaics_chat]

Dies zeigt das Widget im eingebetteten Modus (nicht floating), nützlich für eine dedizierte „Kontakt“-Seite.

5. Die 6 Tools des Agenten

Der Agent verfügt über 6 Tools, die er je nach Frage aufruft oder nicht. Alle sind strikt schreibgeschützt. Sie aktivieren oder deaktivieren jedes einzeln in Einstellungen → Verhalten.

lookup_order

Ruft den Status einer WooCommerce-Bestellung ab. Erfordert obligatorische E-Mail-Verifizierung vor der Offenlegung: Der Agent fragt den Kunden nach seiner E-Mail und gleicht sie mit der Bestell-E-Mail ab. Gibt Bestellnummer, Status, Betrag, Datum, Versandmethode und Sendungsnummer (falls verfügbar) zurück.

search_products

Durchsucht den Katalog nach Name, Kategorie, Tag, Verfügbarkeit, Preisbereich. Gibt standardmäßig bis zu 5 Ergebnisse mit Titel, SKU, Preis, URL, Bestand zurück. Nützlich für Antworten auf „Haben Sie das in Blau?“ oder „Was kostet X?“.

get_shipping_info

Gibt die in WooCommerce konfigurierten Versandzonen und -methoden mit Gebühren und Fristen zurück. Der Agent kann präzise auf „Liefern Sie nach Belgien?“ oder „Was kostet Express?“ antworten.

get_returns_policy

Gibt den Inhalt Ihrer Rückgaberichtlinie zurück (die Sie in den Einstellungen konfigurieren). Der Agent kann Frist, Verfahren und Bedingungen erklären.

search_faq

Durchsucht Ihre individuellen FAQs (verwaltet in AI Support → FAQ). Ergebnisse werden nach Konversationssprache gefiltert. Jeder gefundene Eintrag erhöht einen Nutzungszähler, um die häufigsten Fragen zu identifizieren.

escalate_to_human

Der Agent ruft dieses Tool auf, wenn er feststellt, dass ein Fall einen Menschen erfordert (Kundenfrustration, komplexer Fall, wiederholte Tool-Fehler). Löst konfigurierte Slack- und/oder E-Mail-Benachrichtigungen aus. Siehe Abschnitt Eskalation unten.

6. FAQ-Verwaltung

Erstellen Sie individuelle FAQ-Einträge, die der Agent während einer Konversation durchsuchen kann. Jeder Eintrag ist nach Sprache gefiltert.

Einen Eintrag erstellen

1. Gehen Sie zu AI Support → FAQ
2. Klicken Sie auf Eintrag hinzufügen
3. Wählen Sie die Sprache
4. Formulieren Sie Frage und Antwort in natürlicher Sprache
5. Fügen Sie durch Kommas getrennte Schlüsselwörter hinzu (optional, verbessert die Suche)
6. Wählen Sie eine Kategorie (z. B. Versand, Größen, Garantie)
7. Speichern

FAQ-Best-Practices

• Formulieren Sie Fragen, wie ein Kunde sie stellen würde, nicht wie ein SEO-Texter
• Kurze und umsetzbare Antworten (2 bis 4 Sätze reichen, der Agent formuliert um)
• Erstellen Sie einen Eintrag pro Hauptsprache Ihrer Kundschaft
• Prüfen Sie regelmäßig den Nutzungszähler, um zu erweiternde Fragen zu identifizieren

7. Eskalation an einen Menschen

Die Eskalation wird in Einstellungen → Eskalation konfiguriert. Zwei Kanäle werden parallel unterstützt: Slack und E-Mail.

Slack-Konfiguration

1. Erstellen Sie in Slack eine neue App auf api.slack.com/apps
2. Aktivieren Sie Incoming Webhooks
3. Erstellen Sie einen Webhook zum gewünschten Kanal (z. B. #support-escalations)
4. Kopieren Sie die Webhook-URL
5. Fügen Sie sie in WordPress in Slack Webhook ein
6. Klicken Sie auf Webhook testen, um eine Testnachricht zu senden

Jede Eskalation sendet Slack eine Rich-Block-Nachricht mit: Auszug der letzten 3 Nachrichten, Eskalationsgrund, Kunden-Metadaten (verifizierte E-Mail, Sprache, Ursprungsseite) und einer Schaltfläche Im Admin öffnen, die direkt zum Konversationsdetail führt.

E-Mail-Konfiguration

Geben Sie unter Eskalations-E-Mail eine oder mehrere durch Kommas getrennte Adressen ein. Jede Eskalation sendet eine HTML-E-Mail mit vollständigem Transkript, Kundendaten und einem Admin-Link.

Eskalationsauslöser

Der Agent eskaliert in 3 Situationen:

1. Sensible Schlüsselwörter — Konfigurierbare Liste (Standard: Rückerstattung, Anwalt, kaputt, Reklamation, refund, lawyer, broken, complaint)
2. Sentiment-Schwelle — Erkennung von Frustration oder Unzufriedenheit (einstellbar von -1 bis 0)
3. Wiederholter Tool-Fehler — Nach 6 Runden ohne Lösung: erzwungene Eskalation

8. Dashboard und Analytik

Das Dashboard AI Support → Dashboard zeigt 4 Schlüsselindikatoren:

• Volumen — Gesamtzahl der Konversationen der letzten 7, 30 oder 90 Tage
• Auto-Auflösungsrate — % der Konversationen, die ohne Eskalation enden
• Durchschnittliche Zufriedenheit — Sternebewertung der Kunden nach Eskalation
• Verbrauchte Token — Input + Output kumulativ zur KI-Kostenschätzung

Die Seite Konversationen listet alle Sitzungen mit Filtern (Sprache, Status, Eskalation ja/nein). Klicken Sie auf eine Zeile, um das vollständige Transkript mit detaillierten Tool Calls in JSON zu sehen.

9. Mehrsprachig

Das Plugin unterstützt nativ 5 Sprachen: Französisch, Englisch, Spanisch, Deutsch, Italienisch. Die Konversationssprache wird automatisch in dieser Reihenfolge aufgelöst:

1. Polylang-Sprache der Seite, auf der das Widget angezeigt wird (falls Polylang installiert)
2. WPML-Sprache der Seite (falls WPML installiert)
3. Browser-Locale des Besuchers
4. In den Einstellungen konfigurierte Fallback-Sprache (Standard: Englisch)

Der System-Prompt des Agenten teilt dem Modell explizit die erwartete Antwortsprache mit. Dies stellt sicher, dass ein französischer Besucher eine französische Antwort erhält, auch wenn Ihr Shop überwiegend englisch ist.

10. Sicherheit und Datenschutz

API-Schlüssel-Verschlüsselung

Anthropic-, OpenAI-Schlüssel und der Slack-Webhook werden beim Speichern in AES-256-CBC verschlüsselt, mit einem von AUTH_KEY + AUTH_SALT abgeleiteten Schlüssel. Das Eingabefeld zeigt den Wert nie erneut an: Wenn Sie das Feld leer lassen und speichern, wird der vorherige Wert beibehalten.

E-Mail-Verifizierung für Bestellungen

Das Tool lookup_order erfordert obligatorisch Verifizierung: Der Agent fragt den Kunden nach seiner E-Mail und gleicht sie mit der zur Bestellung gehörenden ab. Ohne Übereinstimmung werden keine Daten offengelegt. Dieses Verhalten kann nicht deaktiviert werden — es schützt vor Bestellungs-Scraping über den Agenten.

Rate Limiting

Ein serverseitiges Anti-Spam-Rate-Limit von 5 Nachrichten pro Minute pro Sitzung wird durchgesetzt. Die maximale Anzahl von Nachrichten pro Konversation ist standardmäßig 25 (konfigurierbar). Darüber hinaus schlägt der Agent eine menschliche Eskalation vor.

Aufbewahrung und DSGVO

Konversationen werden standardmäßig 30 Tage aufbewahrt und dann automatisch durch einen täglichen Cron gelöscht. Sie können diese Dauer in Einstellungen → Datenschutz reduzieren. Die Besucher-IP und der User Agent können je nach Ihrer Richtlinie protokolliert werden oder nicht.

Das Plugin bietet außerdem eine Option PII in Logs anonymisieren, die E-Mails und Telefonnummern in den technischen Logs (WooCommerce Logger) maskiert.

11. HPOS- und Checkout-Blöcke-Kompatibilität

Das Plugin deklariert offiziell Kompatibilität mit:

• HPOS (High-Performance Order Storage) — Alle Bestellabfragen laufen über die offiziellen WooCommerce-CRUDs (wc_get_order, wc_get_orders), funktionieren also sowohl auf Legacy- als auch auf HPOS-Tabellen
• Gutenberg Cart- und Checkout-Blöcke — Keine Störung der neuen Zahlungsblöcke
• WordPress Multisite — Netzwerk-Aktivierung unterstützt, Optionen pro Site

12. Hooks und Filter für Entwickler

Das Plugin stellt mehrere Hooks bereit, um das Verhalten ohne Änderung des Quellcodes anzupassen.

Verfügbare Filter

// System-Prompt vor dem Senden an das Modell ändern
apply_filters('dfaics_system_prompt', $prompt, $context);

// Tools dynamisch hinzufügen oder entfernen
apply_filters('dfaics_tools_available', $tools, $conversation);

// Max-Nachrichten-Schwelle vor erzwungener Eskalation ändern
apply_filters('dfaics_max_messages', 25, $conversation);

// Eskalations-E-Mail-Body anpassen
apply_filters('dfaics_escalation_email_body', $html, $conversation);

// Slack-Metadaten anreichern
apply_filters('dfaics_slack_metadata', $metadata, $conversation);

Verfügbare Aktionen

// Nach Erstellung einer Konversation
do_action('dfaics_conversation_created', $conversation_id, $session);

// Nach Senden einer Nachricht durch den Agenten
do_action('dfaics_message_sent', $message_id, $conversation_id);

// Nach einer Eskalation
do_action('dfaics_escalated', $conversation_id, $reason, $channel);

// Nach Cron-Bereinigung abgelaufener Konversationen
do_action('dfaics_cleanup_done', $deleted_count);

Ein individuelles Tool hinzufügen

Erstellen Sie eine Klasse, die ToolBase erweitert, und registrieren Sie sie über den Filter dfaics_tools_available. Der Namespace ist DataFirefly/AiCustomerService/Agent/Tools (hier mit Schrägstrichen zur Lesbarkeit; verwenden Sie in Ihrem Code den standardmäßigen PHP-Backslash-Separator). Jedes Tool deklariert sein JSON-Schema, seine Beschreibung und implementiert eine execute()-Methode, die ein serialisierbares assoziatives Array zurückgibt.

13. Fehlerbehebung

Das Widget wird nicht angezeigt

• Prüfen Sie, ob das Widget in Einstellungen → Widget → Widget aktivieren aktiviert ist
• Prüfen Sie die Bedingte-Anzeige-Regel (erlaubte Seiten)
• Öffnen Sie die Browser-Konsole (F12) und suchen Sie nach JS-Fehlern
• Leeren Sie den Cache, falls Sie ein Cache-Plugin verwenden (WP Rocket, W3 Total Cache…)

Der Agent antwortet nicht

• Prüfen Sie über die Schaltfläche Schlüssel testen, ob der API-Schlüssel gültig ist
• Prüfen Sie Ihr Guthaben / Kontingent im Anthropic- oder OpenAI-Konto
• Prüfen Sie die WooCommerce-Logs in WooCommerce → Status → Logs, Quelle df-ai-customer-service

Slack-Eskalation kommt nicht an

• Prüfen Sie den Webhook über die Schaltfläche Webhook testen
• Regenerieren Sie den Webhook bei Bedarf auf Slack-Seite
• Prüfen Sie, ob der Zielkanal existiert und der Bot Zugriff hat

Plugin vollständig zurücksetzen

Aktivieren Sie in Einstellungen → Datenschutz die Option Alle Daten bei Deinstallation löschen. Deaktivieren und deinstallieren Sie dann das Plugin: Die 5 Tabellen und Optionen werden entfernt.

14. Technische FAQ

Kann ich den KI-Provider wechseln, ohne Konversationen zu verlieren?

Ja, der Wechsel Claude ↔ OpenAI ist sofort und wirkt sich nicht auf den Verlauf aus. Neue Konversationen verwenden den neuen Provider.

Funktioniert das Plugin im Headless-Modus?

Die REST-API des Plugins (/wp-json/dfaics/v1/) kann von jedem Frontend aus verwendet werden (Next.js, Vue, Mobile). Das native Widget ist Vanilla JS und kann durch Ihre eigene Implementierung ersetzt werden, die dieselbe API aufruft.

Kann man das Plugin an Zendesk oder Freshdesk anbinden?

Nicht nativ in 1.0.0: Die Eskalation ist auf Slack und E-Mail beschränkt. Sie können jedoch den Hook dfaics_escalated verwenden, um Ihre eigene Integration auszulösen.

Lernt der Agent aus meinen Konversationen?

Nein. Es wird kein Fine-Tuning durchgeführt. Der Agent verwendet nur den System-Prompt + Tools + aktuellen Konversationskontext. Ihre Daten werden nicht zur Verbesserung der Anthropic- oder OpenAI-Modelle verwendet (beide Provider bieten eine Opt-out-Option, die auf ihren professionellen APIs standardmäßig aktiv ist).

15. Support

Für Fragen oder Fehlermeldungen schreiben Sie an support at datafirefly.com unter Angabe Ihrer Lizenznummer. Wir antworten innerhalb von 48 Werktagsstunden.