Agent AI Obsługi Klienta: kompletna dokumentacja

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.

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.

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

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.

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

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).

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.