DataFirefly WhatsApp: dokumentacja

Witamy w dokumentacji modułu DataFirefly WhatsApp. Ten przewodnik obejmuje wszystko, czego potrzebujesz, aby zainstalować, skonfigurować i w pełni wykorzystać pływający przycisk WhatsApp z obsługą wielu agentów w PrestaShop 8 i 9.

Instalacja

Moduł instaluje się jak każdy inny moduł PrestaShop, w kilku kliknięciach.

Wymagania

• PrestaShop 8.0.x albo 9.0.x
• PHP 8.0 albo nowsze (zalecane 8.1+)
• MySQL 5.6+ albo MariaDB 10.3+
• Co najmniej jeden numer WhatsApp (prywatny albo Business)

Kroki instalacji

1. Pobierz plik dfwhatsapp-v1.0.0.zip ze swojego konta klienta DataFirefly
2. W back office PrestaShop przejdź do Moduły > Menedżer modułów
3. Kliknij Wgraj moduł w prawym górnym rogu
4. Wybierz plik ZIP i zatwierdź
5. Kliknij Zainstaluj, gdy moduł się pojawi
6. Kliknij Konfiguruj, aby otworzyć ekran ustawień

Konfiguracja ogólna

Strona konfiguracji modułu jest podzielona na 6 zakładek, aby dało się ustawić wszystko bez gubienia się.

Zakładka Ogólne

• Włącz moduł: przełącznik główny, wyłącza przycisk w całym sklepie
• Tryb wyboru agenta: round-robin, losowy, pierwszy dostępny albo ręczny
• Włącz śledzenie: niezbędne, aby zasilać pulpit analityczny
• Kod QR na desktopie: pokazuje kod QR zamiast otwierania WhatsApp Web na komputerach stacjonarnych

Zakładka Wygląd

• Pozycja: cztery możliwe rogi (dolny prawy, dolny lewy, górny prawy, górny lewy)
• Kolor: domyślnie zieleń WhatsAppa #25D366
• Rozmiar ikony: w pikselach (domyślnie 60)
• Przesunięcie X i Y: odległość od krawędzi ekranu
• Animacja: pulsowanie, odbicie, potrząśnięcie albo brak
• Etykieta tekstowa: opcjonalna etykieta wyświetlana obok przycisku

Zakładka Komunikaty

Osobny, wstępnie wypełniony komunikat dla każdego typu strony (produkt, koszyk, kategoria, CMS, zamówienie, strona główna), przetłumaczony na 4 dołączone języki.

Zakładka Harmonogram

• Tryb poza godzinami pracy:
  • hide: przycisk znika całkowicie
  • show_offline: przycisk pozostaje widoczny, wyszarzony, z komunikatem oczekiwania
  • callback: formularz oddzwonienia zastępuje bezpośrednią rozmowę
• Komunikat poza godzinami pracy: tekst wyświetlany, gdy wszyscy agenci są offline

Zakładka RODO

• Włącz zgodę: wyświetla treść zgody przed każdym otwarciem WhatsAppa
• Treść zgody: konfigurowalna per język

Zakładka Wykluczenia

• Wykluczone strony: lista kontrolerów (na przykład checkout, identity)
• Wykluczone kategorie: identyfikatory kategorii oddzielone przecinkami
• Wykluczone produkty: identyfikatory produktów oddzielone przecinkami

Zarządzanie agentami

To serce modułu: tutaj dodajesz osoby, które będą odbierać wiadomości WhatsApp.

Dodanie agenta

1. Przejdź do Sprzedaj > Katalog > Agenci WhatsApp
2. Kliknij Dodaj
3. Uzupełnij:
   • Nazwa: nazwa wyświetlana klientowi (na przykład „Alex”)
   • Telefon: w formacie międzynarodowym bez spacji (na przykład 48601234567)
   • Dział: dowolny tekst (wsparcie, sprzedaż, dział techniczny)
   • Awatar: opcjonalny obraz (png, jpg, svg, webp)
   • Pozycja: kolejność wyświetlania w trybie ręcznym
   • Rola: tekst tłumaczony na 4 języki (na przykład „Wsparcie techniczne”)
   • Własny komunikat: opcjonalne nadpisanie komunikatów kontekstowych

Ustawienie godzin agenta

Bezpośrednio w formularzu agenta tygodniowa tabela pozwala określić:

• Kilka przedziałów dziennie (na przykład 9:00 do 12:30 oraz 14:00 do 18:30)
• Pusty dzień oznacza, że agent jest tego dnia offline
• Agent bez żadnego zdefiniowanego przedziału jest traktowany jako zawsze dostępny (tryb 24/7)

Dodanie wyjątku (dzień wolny, urlop)

1. W formularzu agenta, w sekcji Wyjątki
2. Podaj datę początkową i datę końcową
3. Dodaj opcjonalny opis (na przykład „Urlop letni”)

Zmienne kontekstowe

Wstępnie wypełniane komunikaty obsługują 12 zmiennych, podstawianych w locie zależnie od strony, na której znajduje się klient:

• {product_name}: nazwa produktu (karta produktu)
• {product_url}: pełny adres produktu
• {product_price}: cena sformatowana wraz z walutą
• {product_ref}: referencja produktu
• {customer_name}: nazwa klienta, jeśli jest zalogowany
• {cart_id}: identyfikator koszyka
• {cart_total}: sformatowana suma koszyka
• {cart_summary}: lista pozycji w koszyku
• {order_ref}: numer zamówienia
• {order_total}: suma zamówienia
• {category_name}: nazwa bieżącej kategorii
• {shop_name}: nazwa sklepu

Tryby kierowania do agentów

Round-robin

Moduł kolejno zmienia dostępnych agentów przy każdym nowym otwarciu, naturalnie równoważąc obciążenie.

Losowy

Agent jest losowany spośród dostępnych. Przydatne, gdy równy podział między agentami nie jest krytyczny.

Pierwszy dostępny

Wybierany jest pierwszy agent z listy (według pozycji), który jest aktualnie dostępny.

Ręczny

Klient widzi popup z listą dostępnych agentów (awatar, nazwa, rola, status) i sam wybiera rozmówcę.

Analityka i RODO

Pulpit

Dostępny w Sprzedaj > Katalog > WhatsApp Analytics, pokazuje:

• Łączną liczbę kliknięć w okresie
• Liczbę unikalnych odwiedzających (przez hash adresu IP)
• Stosunek kliknięć do odwiedzającego
• Rozkład per dzień, per typ strony i per agent
• Top 20 produktów wyzwalających rozmowy

Ochrona danych

Kod QR na desktopie

Na komputerach stacjonarnych zamiast otwierać WhatsApp Web (co wymusza na kliencie każdorazowe skanowanie kodu QR) możesz włączyć tryb bezpośredniego kodu QR:

• Moduł generuje kod QR zawierający link wa.me z wypełnionym komunikatem
• Klient skanuje go telefonem
• WhatsApp otwiera się od razu na jego telefonie, z wiadomością gotową do wysłania

Ten tryb utrzymuje rozmowę na kanale preferowanym przez klienta, bez dodatkowego tarcia.

Formularz oddzwonienia

Gdy wszyscy Twoi agenci są offline, a wybrałeś tryb callback:

1. Klient widzi formularz zamiast zwykłej rozmowy
2. Podaje imię, telefon i opcjonalną wiadomość
3. Zgłoszenie trafia do tabeli ps_dfwhatsapp_callback ze statusem pending
4. Zgłoszenia możesz przeglądać przez phpMyAdmin albo zbudować własny raport

Wielojęzyczność

Moduł jest dostarczany z 4 kompletnymi językami: francuskim, angielskim, hiszpańskim i niemieckim. Wszystkie teksty widoczne po stronie klienta są przetłumaczone:

• Komunikaty kontekstowe per strona
• Treść zgody RODO
• Komunikat powitalnego popupu
• Etykiety agentów (rola, status)
• Interfejs formularza oddzwonienia
• Komunikat poza godzinami pracy

Możesz też ustawić inną rolę i inny własny komunikat dla każdego języka i każdego agenta, bezpośrednio w formularzu agenta, przełączając zakładkę języka.

Zgodność

• PrestaShop 8.0.x, 8.1.x, 8.2.x, 9.0.x
• PHP 8.0 do 8.3
• Multistore: tak (osobne konfiguracje per sklep)
• Wielojęzyczność: tak (Polylang niewymagany)
• Cache: zgodny (Hummingbird, LSCache, Redis)
• Nadpisania klas core: brak

Rozwiązywanie problemów

Przycisk się nie wyświetla

1. Sprawdź, czy moduł jest włączony w zakładce Ogólne
2. Sprawdź, czy istnieje co najmniej jeden agent ze statusem Aktywny
3. Sprawdź, czy bieżąca strona nie znajduje się na liście wykluczeń
4. Wyczyść pamięć podręczną PrestaShop (Zaawansowane parametry > Wydajność)
5. Wyczyść pamięć podręczną przeglądarki (Ctrl+Shift+R)

Kliknięcie w przycisk nic nie robi

1. Otwórz konsolę przeglądarki (F12) i sprawdź, czy nie ma błędu JavaScript
2. Sprawdź, czy inny moduł nie blokuje skryptu modułu
3. Sprawdź, czy plik dfwhatsapp.js faktycznie ładuje się w kodzie HTML

Statystyki nie rosną

1. Sprawdź, czy śledzenie jest włączone w zakładce Ogólne
2. Sprawdź, czy blokada reklam po stronie klienta nie filtruje adresu module/dfwhatsapp/track
3. Zajrzyj do tabeli ps_dfwhatsapp_click, aby sprawdzić, czy zdarzenia docierają

Błąd SQL „LIMIT 1 LIMIT 1″

Poprawiony w wersji 1.0.1. Zaktualizuj moduł do najnowszej wersji ze swojego konta klienta DataFirefly.

Wsparcie i aktualizacje

• Wsparcie e-mail: hello@datafirefly.com
• Aktualizacje w cenie przez 12 miesięcy, do pobrania z konta klienta
• Zgodność PS 8 i PS 9 zapewniona bez dopłaty

Historia zmian

1.0.0, 13 maja 2026, premiera

• Pierwsza wersja publiczna
• Obsługa wielu agentów z czterema trybami kierowania
• Tygodniowy harmonogram per agent z wyjątkami
• Powitalny popup, kod QR na desktopie, formularz oddzwonienia
• Natywna zgoda RODO i analityka z hashowanym adresem IP
• Cztery języki: FR, EN, ES, DE
• Zgodność z PrestaShop 8.0+ i 9.0+