# KI-Kundenservice-Agent — Vollständige Dokumentation
> Vollständige Anleitung zum DataFirefly-AI-Customer-Service-Agent-Plugin für WooCommerce: Installation, Claude/OpenAI-Konfiguration, Widget-Anpassung, Agenten-Tools, Slack- und E-Mail-Eskalation, mehrsprachig, DSGVO-Sicherheit, Entwickler-Hooks.
- Seite:
- Sprache: de
- Aktualisiert am: 2026-07-01
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/agent-ia-service-client/index.md), [en](https://www.datafirefly.com/en/documentation/agent-ia-service-client/index.md), [es](https://www.datafirefly.com/es/documentation/agent-ia-service-client/index.md), [it](https://www.datafirefly.com/it/documentation/agent-ia-service-client/index.md), [pl](https://www.datafirefly.com/pl/documentation/agent-ia-service-client/index.md), [nl](https://www.datafirefly.com/nl/documentation/agent-ia-service-client/index.md), [pt](https://www.datafirefly.com/pt/documentation/agent-ia-service-client/index.md)
- Index:
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.
**Für wen ist dieses Plugin?** WooCommerce-Shops, die pro Woche Dutzende bis Hunderte Tickets erhalten, meist zu Bestellstatus, Versand, Rückgaben und Größen. Der Agent bearbeitet automatisch rund 70 % dieser Level-1-Anfragen in 5 Sprachen und leitet den Rest mit vollem Kontext an einen Menschen weiter.
## 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.
Nach der Aktivierung erscheint ein neues Menü **AI Support** in der WordPress-Admin-Seitenleiste mit 4 Unterseiten: Dashboard, Konversationen, FAQ, Einstellungen.
## 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](https://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](https://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)
**Sicherheit.** API-Schlüssel werden im Ruhezustand in AES-256-CBC verschlüsselt, mit einem von `AUTH_KEY` und `AUTH_SALT` (Konstanten aus Ihrer `wp-config.php`) abgeleiteten Schlüssel. Sie werden nach der ersten Eingabe nie im Klartext angezeigt. Wenn Sie `AUTH_KEY` ändern, müssen Sie Ihre Schlüssel neu eingeben.
### 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.
**Sicherheit by Design.** Kein Tool schreibt in die Datenbank. Das Plugin kann weder eine Bestellung ändern, noch erstatten, noch ein Passwort ändern, noch dem Kunden eine E-Mail senden. Jede solche Aktion muss über einen menschlichen Operator per Eskalation erfolgen.
## 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](https://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
Der Agent kann auch von sich aus eskalieren, wenn das Schlüsselwort nicht ausgelöst wird, er den Fall aber als außerhalb seines Kompetenzbereichs einschätzt. Das ist das native Verhalten von Tool Calling.
## 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.
**Keine Daten werden an DataFirefly gesendet.** Alle KI-Anfragen laufen direkt zwischen Ihrem WordPress und dem gewählten Provider (Anthropic oder OpenAI), mit Ihrem eigenen API-Schlüssel. DataFirefly hat keinen Zugriff auf Konversationen.
## 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.