# Agent AI Obsługi Klienta: kompletna dokumentacja
> Kompletny przewodnik po wtyczce DataFirefly AI Customer Service Agent dla WooCommerce: instalacja, konfiguracja Claude/OpenAI, personalizacja widżetu, narzędzia agenta, eskalacja do Slacka i na e-mail, wielojęzyczność, bezpieczeństwo i RODO, hooki dla deweloperów.
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [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), [de](https://www.datafirefly.com/de/documentation/agent-ia-service-client/index.md), [it](https://www.datafirefly.com/it/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)
- Indeks:
Kompletny przewodnik po instalacji, konfiguracji i użytkowaniu wtyczki **DataFirefly AI Customer Service Agent**: agenta AI obsługi klienta dla WooCommerce, który rozumie kontekst, wywołuje narzędzia tylko do odczytu w Twoim sklepie i inteligentnie eskaluje złożone przypadki do Slacka i na e-mail.
**Dla kogo jest ta wtyczka?** Dla sklepów WooCommerce otrzymujących od kilkudziesięciu do kilkuset zgłoszeń tygodniowo, z których większość dotyczy statusu zamówienia, dostawy, zwrotów i rozmiarów. Agent obsługuje automatycznie około 70 % takich zapytań pierwszej linii w 5 językach, a resztę przekazuje człowiekowi z pełnym kontekstem.
## 1. Wymagania
- **WordPress** 6.4 lub nowszy
- **WooCommerce** 8.0 lub nowszy
- **PHP** 8.1, 8.2 albo 8.3
- **Klucz API** Anthropic (Claude) _albo_ OpenAI (zalecane: Claude Sonnet 4.5)
- Opcjonalnie: webhook Slacka do eskalacji w czasie rzeczywistym
- Opcjonalnie: Polylang Pro albo WPML, jeśli Twój sklep jest wielojęzyczny
## 2. Instalacja
### Instalacja ZIP-a
1. Ze swojego konta DataFirefly pobierz plik `df-ai-customer-service.zip`
2. W WordPressie przejdź do **Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer**
3. Wybierz ZIP i kliknij **Zainstaluj**
4. Po zakończeniu instalacji kliknij **Włącz**
### Co dzieje się przy aktywacji?
Wtyczka automatycznie tworzy 5 tabel w bazie z przedrostkiem `wp_dfaics_`: conversations, messages, escalations, faq, analytics. Deklaruje też zgodność z HPOS oraz blokami Gutenberga cart/checkout, a następnie planuje codzienne zadanie cron czyszczące wygasłe rozmowy.
Po aktywacji w pasku bocznym administracji WordPressa pojawia się nowe menu **AI Support** z 4 podstronami: Panel, Rozmowy, FAQ, Ustawienia.
## 3. Konfiguracja dostawcy AI
Wtyczka obsługuje dwóch dostawców AI. Wybierasz preferowanego w **AI Support → Ustawienia → AI**. Podajesz własny klucz API: DataFirefly niczego nie przechwytuje i nie pobiera prowizji od Twojego zużycia.
### Opcja A: Claude (zalecane)
1. Załóż konto na [console.anthropic.com](https://console.anthropic.com)
2. Wygeneruj klucz API w **Settings → API Keys**
3. Skopiuj klucz (zaczyna się od `sk-ant-...`)
4. W WordPressie przejdź do **AI Support → Ustawienia → AI**
5. Wybierz dostawcę **Anthropic (Claude)**
6. Wklej klucz w pole _Klucz API Anthropic_
7. Model domyślny: `claude-sonnet-4-5` (świetny stosunek jakości do kosztu)
8. Kliknij **Testuj klucz**, aby zweryfikować
9. Zapisz
### Opcja B: OpenAI
1. Załóż konto na [platform.openai.com](https://platform.openai.com)
2. Wygeneruj klucz API w **API Keys**
3. Skopiuj klucz (zaczyna się od `sk-...`)
4. W WordPressie wybierz dostawcę **OpenAI**
5. Model domyślny: `gpt-4o-mini` (najbardziej ekonomiczny z niezawodnym tool callingiem)
**Bezpieczeństwo.** Klucze API są szyfrowane w spoczynku algorytmem AES-256-CBC kluczem wyprowadzonym z `AUTH_KEY` i `AUTH_SALT` (stałe z Twojego `wp-config.php`). Po pierwszym wpisaniu nigdy nie są już wyświetlane otwartym tekstem. Jeśli zmienisz `AUTH_KEY`, będziesz musiał wpisać klucze ponownie.
### Koszt orientacyjny
Typowa rozmowa złożona z 5 do 10 wymian z tool callingiem kosztuje:
- Około **0,01 do 0,05 USD** przy Claude Sonnet 4.5
- Około **0,005 do 0,02 USD** przy GPT-4o mini
Panel pokazuje łączną liczbę zużytych tokenów wejściowych i wyjściowych w danym okresie.
## 4. Konfiguracja widżetu
Widżet czatu wyświetla się domyślnie w prawym dolnym rogu na wszystkich stronach frontu. Personalizuj go w **AI Support → Ustawienia → Widżet**.
### Opcje wyglądu
- **Kolor główny**: kolor pływającego przycisku i nagłówka (domyślnie `#0073aa`)
- **Kolor tekstu**: kolor tekstu w nagłówku (domyślnie biały)
- **Pozycja**: prawy dolny albo lewy dolny róg
- **Tytuł widżetu**: np. „Potrzebujesz pomocy?"
- **Wiadomość powitalna**: pierwsza wiadomość wyświetlana przy otwarciu
- **Placeholder**: tekst pola wpisywania
- **Pokaż odznakę DataFirefly**: drobna wzmianka na dole widżetu
### Wyświetlanie warunkowe
W zakładce **Widżet** możesz ograniczyć wyświetlanie:
- **Wszystkie strony**: zachowanie domyślne
- **Tylko strony produktów**: wsparcie skupione na kartach produktów
- **Poza koszykiem i checkoutem**: bez rozpraszania podczas zakupu
- **Ukryj na tych ID treści**: lista identyfikatorów do wykluczenia
### Shortcode
Czat możesz też osadzić na stronie albo we wpisie shortcodem:
```
[dfaics_chat]
```
Wyświetla to widżet w trybie osadzonym (nie pływającym), wygodnym na dedykowanej stronie „Kontakt".
## 5. 6 narzędzi agenta
Agent dysponuje 6 narzędziami, które wywołuje albo nie, zależnie od pytania. Wszystkie są **ściśle tylko do odczytu**. Włączasz je i wyłączasz pojedynczo w **Ustawienia → Zachowanie**.
### lookup_order
Pobiera status zamówienia WooCommerce. **Wymaga obowiązkowej weryfikacji adresu e-mail** przed ujawnieniem: agent prosi klienta o e-mail i porównuje go z adresem zamówienia. Zwraca numer, status, kwotę, datę, metodę dostawy i numer śledzenia, jeśli jest dostępny.
### search_products
Przeszukuje katalog po nazwie, kategorii, tagu, dostępności i przedziale cenowym. Zwraca domyślnie do 5 wyników z tytułem, SKU, ceną, adresem URL i stanem magazynowym. Przydatne przy pytaniach „czy macie to w kolorze niebieskim?" albo „ile kosztuje X?".
### get_shipping_info
Zwraca strefy i metody dostawy skonfigurowane w WooCommerce, wraz z kosztami i terminami. Agent może więc precyzyjnie odpowiedzieć na „czy dostarczacie do Belgii?" albo „ile kosztuje ekspres?".
### get_returns_policy
Zwraca treść Twojej polityki zwrotów (konfigurowanej w ustawieniach). Agent może wyjaśnić termin, procedurę i warunki.
### search_faq
Przeszukuje Twoje własne FAQ (zarządzane w **AI Support → FAQ**). Wyniki są ograniczone do języka rozmowy. Każdy znaleziony wpis zwiększa licznik użycia, co pomaga zidentyfikować najczęstsze pytania.
### escalate_to_human
Agent wywołuje to narzędzie, gdy uzna, że sprawa wymaga człowieka (frustracja klienta, złożony przypadek, kilka nieudanych wywołań narzędzi). Wyzwala skonfigurowane powiadomienia w Slacku i na e-mail. Patrz sekcja _Eskalacja_ poniżej.
**Bezpieczeństwo z założenia.** Żadne narzędzie nie zapisuje do bazy. Wtyczka nie może zmodyfikować zamówienia, zwrócić pieniędzy, zmienić hasła ani wysłać e-maila do klienta. Każde takie działanie musi przejść przez człowieka po eskalacji.
## 6. Zarządzanie FAQ
Twórz własne wpisy FAQ, które agent może przeszukiwać podczas rozmowy. Każdy wpis jest **przypisany do języka**.
### Tworzenie wpisu
1. Przejdź do **AI Support → FAQ**
2. Kliknij **Dodaj wpis**
3. Wybierz język
4. Sformułuj pytanie i odpowiedź naturalnym językiem
5. Dodaj słowa kluczowe rozdzielone przecinkami (opcjonalnie, poprawia wyszukiwanie)
6. Wybierz kategorię (np. dostawa, rozmiary, gwarancja)
7. Zapisz
### Dobre praktyki FAQ
- Formułuj pytania tak, jak zadałby je klient, nie jak redaktor SEO
- Odpowiedzi krótkie i konkretne (2 do 4 zdań wystarczy, agent i tak przeformułuje)
- Utwórz wpis dla każdego głównego języka Twoich klientów
- Regularnie sprawdzaj licznik użycia, aby wskazać pytania warte rozbudowania
## 7. Eskalacja do człowieka
Eskalację konfiguruje się w **Ustawienia → Eskalacja**. Obsługiwane są równolegle dwa kanały: Slack i e-mail.
### Konfiguracja Slacka
1. W Slacku utwórz nową aplikację na [api.slack.com/apps](https://api.slack.com/apps)
2. Włącz **Incoming Webhooks**
3. Utwórz webhook do wybranego kanału (np. `#support-escalations`)
4. Skopiuj adres URL webhooka
5. W WordPressie wklej go w pole _Webhook Slacka_
6. Kliknij **Testuj webhook**, aby wysłać wiadomość testową
Każda eskalacja wysyła do Slacka wiadomość w bogatych blokach zawierającą: wyciąg z 3 ostatnich wiadomości, powód eskalacji, metadane klienta (zweryfikowany e-mail, język, strona źródłowa) oraz przycisk **Otwórz w panelu** prowadzący prosto do szczegółów rozmowy.
### Konfiguracja e-mail
W polu _E-mail eskalacji_ podaj jeden lub kilka adresów rozdzielonych przecinkami. Każda eskalacja wysyła e-mail HTML zawierający pełną transkrypcję, dane klienta i link do panelu.
### Wyzwalacze eskalacji
Agent eskaluje w 3 sytuacjach:
1. **Słowa kluczowe wrażliwe**: konfigurowalna lista (domyślnie: zwrot pieniędzy, prawnik, zepsute, reklamacja, complaint, refund, lawyer, broken)
2. **Próg sentymentu**: wykrycie frustracji albo niezadowolenia (ustawiany od -1 do 0)
3. **Powtarzające się niepowodzenia narzędzi**: po 6 turach bez rozwiązania eskalacja wymuszona
Agent może też eskalować z własnej inicjatywy, gdy słowo kluczowe nie zostało wyzwolone, ale uzna sprawę za wykraczającą poza swoje kompetencje. To natywne zachowanie tool callingu.
## 8. Panel i analityka
Panel **AI Support → Panel** pokazuje 4 kluczowe wskaźniki:
- **Wolumen**: łączna liczba rozmów z ostatnich 7, 30 albo 90 dni
- **Wskaźnik samodzielnego rozwiązania**: % rozmów kończących się bez eskalacji
- **Średnia satysfakcja**: ocena w gwiazdkach wystawiana przez klientów po eskalacji
- **Zużyte tokeny**: suma wejściowych i wyjściowych do oszacowania kosztu AI
Strona **Rozmowy** wymienia wszystkie sesje z filtrami (język, status, eskalacja tak/nie). Kliknij wiersz, aby zobaczyć pełną transkrypcję ze szczegółowymi wywołaniami narzędzi w JSON.
## 9. Wielojęzyczność
Wtyczka natywnie obsługuje 5 języków: francuski, angielski, hiszpański, niemiecki, włoski. Język rozmowy jest ustalany automatycznie w tej kolejności:
1. Język Polylang strony, na której wyświetla się widżet (jeśli Polylang jest zainstalowany)
2. Język WPML strony (jeśli WPML jest zainstalowany)
3. Locale przeglądarki odwiedzającego
4. Język zapasowy skonfigurowany w ustawieniach (domyślnie angielski)
Prompt systemowy agenta wprost wskazuje modelowi oczekiwany język odpowiedzi. Gwarantuje to, że francuski odwiedzający otrzyma odpowiedź po francusku, nawet jeśli Twój sklep jest głównie anglojęzyczny.
## 10. Bezpieczeństwo i prywatność
### Szyfrowanie kluczy API
Klucze Anthropic, OpenAI i webhook Slacka są szyfrowane w AES-256-CBC przy zapisie, kluczem wyprowadzonym z `AUTH_KEY` + `AUTH_SALT`. Pole input nigdy nie wyświetla wartości ponownie: pozostawienie pola pustego przy zapisie zachowuje poprzednią wartość.
### Weryfikacja e-mail przy zamówieniach
Narzędzie `lookup_order` obowiązkowo wymaga weryfikacji: agent prosi klienta o e-mail i porównuje go z adresem powiązanym z zamówieniem. Bez zgodności żadne dane nie są ujawniane. Tego zachowania nie da się wyłączyć, chroni ono przed wyciąganiem danych o zamówieniach przez agenta.
### Rate limiting
Antyspamowy limit **5 wiadomości na minutę na sesję** jest egzekwowany po stronie serwera. Maksymalna liczba wiadomości w rozmowie to domyślnie 25 (konfigurowalne). Powyżej agent proponuje eskalację do człowieka.
### Retencja i RODO
Rozmowy są przechowywane domyślnie 30 dni, a następnie automatycznie usuwane przez codzienne zadanie cron. Możesz skrócić ten okres w **Ustawienia → Prywatność**. Adres IP odwiedzającego i user agent mogą być logowane albo nie, zależnie od Twojej polityki.
Wtyczka oferuje też opcję _Anonimizuj dane osobowe w logach_, która maskuje adresy e-mail i numery telefonów w dziennikach technicznych (logger WooCommerce).
**Żadne dane nie trafiają do DataFirefly.** Wszystkie zapytania AI idą bezpośrednio między Twoim WordPressem a wybranym dostawcą (Anthropic albo OpenAI), z Twoim własnym kluczem API. DataFirefly nie ma żadnego dostępu do rozmów.
## 11. Zgodność z HPOS i blokami checkoutu
Wtyczka oficjalnie deklaruje zgodność z:
- **HPOS** (High-Performance Order Storage): wszystkie zapytania o zamówienia idą przez oficjalne CRUD-y WooCommerce (`wc_get_order`, `wc_get_orders`), działają więc zarówno na starych tabelach, jak i na tabelach HPOS
- **Blokami Gutenberga cart i checkout**: żadnej ingerencji w nowe bloki płatności
- **Multisite WordPress**: aktywacja sieciowa obsługiwana, opcje przypisane per witryna
## 12. Hooki i filtry dla deweloperów
Wtyczka udostępnia kilka hooków do personalizacji zachowania bez modyfikowania kodu źródłowego.
### Dostępne filtry
```
// Modify the system prompt before sending it to the model
apply_filters('dfaics_system_prompt', $prompt, $context);
// Add or remove tools dynamically
apply_filters('dfaics_tools_available', $tools, $conversation);
// Change the max message threshold before forced escalation
apply_filters('dfaics_max_messages', 25, $conversation);
// Customize the escalation email body
apply_filters('dfaics_escalation_email_body', $html, $conversation);
// Enrich Slack metadata
apply_filters('dfaics_slack_metadata', $metadata, $conversation);
```
### Dostępne akcje
```
// After a conversation is created
do_action('dfaics_conversation_created', $conversation_id, $session);
// After the agent sends a message
do_action('dfaics_message_sent', $message_id, $conversation_id);
// After an escalation
do_action('dfaics_escalated', $conversation_id, $reason, $channel);
// After the cron cleanup of expired conversations
do_action('dfaics_cleanup_done', $deleted_count);
```
### Dodanie własnego narzędzia
Utwórz klasę rozszerzającą `ToolBase` i zarejestruj ją przez filtr `dfaics_tools_available`. Przestrzeń nazw to `DataFireflyAiCustomerServiceAgentTools`. Każde narzędzie deklaruje swój schemat JSON i opis oraz implementuje metodę `execute()` zwracającą serializowalną tablicę asocjacyjną.
## 13. Rozwiązywanie problemów
### Widżet się nie wyświetla
- Sprawdź, czy widżet jest włączony w **Ustawienia → Widżet → Włącz widżet**
- Sprawdź regułę wyświetlania warunkowego (dozwolone strony)
- Otwórz konsolę przeglądarki (F12) i poszukaj błędów JS
- Wyczyść cache, jeśli używasz wtyczki cache (WP Rocket, W3 Total Cache i podobne)
### Agent nie odpowiada
- Sprawdź poprawność klucza API przyciskiem **Testuj klucz**
- Sprawdź środki i limity na koncie Anthropic albo OpenAI
- Przejrzyj logi WooCommerce w **WooCommerce → Status → Dzienniki**, źródło `df-ai-customer-service`
### Eskalacja na Slacka nie dociera
- Sprawdź webhook przyciskiem **Testuj webhook**
- W razie potrzeby wygeneruj webhook ponownie po stronie Slacka
- Sprawdź, czy kanał docelowy istnieje i czy bot ma do niego dostęp
### Całkowity reset wtyczki
W **Ustawienia → Prywatność** zaznacz _Usuń wszystkie dane przy deinstalacji_. Następnie wyłącz i odinstaluj wtyczkę: 5 tabel i opcje zostaną usunięte.
## 14. FAQ techniczne
### Czy mogę zmienić dostawcę AI bez utraty rozmów?
Tak, przełączenie Claude ↔ OpenAI jest natychmiastowe i nie wpływa na historię. Nowe rozmowy użyją nowego dostawcy.
### Czy wtyczka działa w trybie headless?
API REST wtyczki (`/wp-json/dfaics/v1/`) można używać z dowolnego frontu (Next.js, Vue, mobile). Natywny widżet napisany jest w czystym JavaScripcie i można go zastąpić własną implementacją wywołującą to samo API.
### Czy da się podpiąć wtyczkę pod Zendesk albo Freshdesk?
Nie natywnie w wersji 1.0.0: eskalacja ogranicza się do Slacka i e-maila. Możesz jednak użyć hooka `dfaics_escalated`, aby uruchomić własną integrację.
### Czy agent uczy się z moich rozmów?
Nie. Żaden fine-tuning nie jest wykonywany. Agent korzysta wyłącznie z promptu systemowego, narzędzi i kontekstu bieżącej rozmowy. Twoje dane nie są używane do ulepszania modeli Anthropic ani OpenAI (obaj dostawcy oferują opcję opt-out, aktywną domyślnie w ich API profesjonalnych).
## 15. Wsparcie
W razie pytań albo zgłoszenia błędu napisz na **support at datafirefly.com**, podając numer licencji. Odpowiadamy w ciągu 48 godzin roboczych.