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

- Strona: <https://www.datafirefly.com/pl/documentation/dfwhatsapp/>
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfwhatsapp/index.md), [en](https://www.datafirefly.com/en/documentation/dfwhatsapp/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsapp/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsapp/index.md), [it](https://www.datafirefly.com/it/documentation/dfwhatsapp/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsapp/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwhatsapp/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

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ń

**Wskazówka:** moduł automatycznie tworzy 6 tabel w Twojej bazie danych i dodaje dwie pozycje menu w **Sprzedaj > Katalog**: zarządzanie agentami i pulpit analityczny.

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

**Do zapamiętania:** możesz też dodawać wyjątki _globalne_, obowiązujące wszystkich agentów, pozostawiając identyfikator agenta równy 0 w bazie danych.

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

**Zgodność z RODO:**

- Jawna zgoda wyświetlana przed każdym otwarciem WhatsAppa
- Adres IP odwiedzającego hashowany w **SHA-256** z solą właściwą dla Twojego sklepu (`PS_SHOP_DOMAIN` plus `_COOKIE_KEY_`)
- Żadne bezpośrednie dane osobowe nie są przechowywane
- Żadne pliki cookie firm trzecich nie są zapisywane

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

**Polski sklep:** interfejs modułu nie jest dostarczany po polsku. Teksty widoczne dla klienta (komunikaty kontekstowe, treść zgody, komunikat poza godzinami pracy, rola agenta) wprowadzasz ręcznie po polsku w formularzach modułu, przełączając zakładkę języka, o ile polski jest aktywnym językiem Twojego sklepu.

## 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](mailto: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+