# WhatsApp Commerce Suite Shopware — przewodnik instalacji i konfiguracji
> Wymagania Shopware 6.5, 6.6 lub 6.7 (jedna baza kodu), PHP minimum 8.1 Konto WhatsApp Business ze zweryfikowanym numerem w Meta Business Suite Aplikacja Meta typu Business z włączonym produktem WhatsApp…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-06
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfwhatsappcommerce-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/dfwhatsappcommerce-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsappcommerce-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsappcommerce-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dfwhatsappcommerce-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsappcommerce-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwhatsappcommerce-shopware/index.md)
- Indeks:
## Wymagania
- Shopware 6.5, 6.6 lub 6.7 (jedna baza kodu), PHP minimum 8.1
- Konto **WhatsApp Business** ze zweryfikowanym numerem w Meta Business Suite
- Aplikacja Meta typu **Business** z włączonym produktem WhatsApp
- Aktywny worker kolejek i runner zadań zaplanowanych Shopware (`messenger:consume` i `scheduled-task:run`)
## Instalacja
1. Skopiuj katalog `DfWhatsAppCommerce` do `custom/plugins/` (lub wgraj zip przez Rozszerzenia → Moje rozszerzenia).
2. Zainstaluj i aktywuj: ``` bin/console plugin:refresh bin/console plugin:install --activate DfWhatsAppCommerce bin/console cache:clear ```
3. Skompiluj panel administracyjny i storefront: ``` bin/build-administration.sh bin/build-storefront.sh ```
Instalacja tworzy 5 dedykowanych tabel z prefiksem `df_wac_` oraz 2 zadania zaplanowane (przypomnienia o koszyku co 15 min, godzinowy batch katalogu). Przy odinstalowaniu wszystko jest czysto usuwane, chyba że zaznaczysz „zachowaj dane".
## Konfiguracja Meta Cloud API
### 1. Pozyskanie danych dostępowych
Na [developers.facebook.com](https://developers.facebook.com) utwórz aplikację Business i dodaj produkt WhatsApp. Pozyskaj: **token stały** (użytkownik systemowy z uprawnieniami `whatsapp_business_messaging` i `catalog_management`), **Phone number ID**, **WABA ID** oraz **App secret** (Ustawienia aplikacji → Podstawowe).
### 2. Utworzenie katalogu
W Meta Commerce Manager utwórz katalog i połącz go z kontem WhatsApp Business. Zanotuj **ID katalogu**.
### 3. Konfiguracja webhooka
W aplikacji Meta → WhatsApp → Konfiguracja:
- URL zwrotny: `https://twojsklep.tld/df-wac/webhook`
- Token weryfikacyjny: wartość wpisana w konfiguracji wtyczki (pole „Webhook verify token")
- Subskrybuj pole `messages`
Wpisz **App secret** w konfiguracji wtyczki: bez niego podpis `X-Hub-Signature-256` webhooków nie jest walidowany.
### 4. Wprowadzenie konfiguracji w Shopware
Ustawienia → System → Wtyczki → DataFirefly WhatsApp Commerce Suite. Wypełnij kartę „Meta Cloud API", a następnie przetestuj z poziomu panelu (Marketing → WhatsApp Commerce): przycisk **Testuj połączenie API** i wysyłka wiadomości testowej.
## 4 moduły
### Katalog Meta
Trzy tryby: czas rzeczywisty (przy każdym zapisie produktu), batch godzinowy lub ręczny. Warianty wysyłane są pojedynczo z `retailer_id` `sw_{numer artykułu}`. W razie potrzeby wyklucz kategorie. Pełną resynchronizację (partie po 100) uruchomisz z panelu.
### Zamówienia konwersacyjne
6-poziomowa maszyna stanów. Rozpoznawane słowa kluczowe (FR/EN/DE): `menu`, `cart`, `pay`, `human`, `reset`, `help`. Język klienta wykrywany jest automatycznie. Przekazanie do człowieka wysyła e-mail na skonfigurowany adres z linkiem do konwersacji.
### Odzyskiwanie porzuconych koszyków
3 konfigurowalne przypomnienia (domyślnie 60 min, 24 h, 72 h) wysyłane przez zadanie zaplanowane co 15 minut do klientów ze znanym numerem telefonu z adresu rozliczeniowego. Kod promocyjny wpisany w konfiguracji dołączany jest do 3. przypomnienia i automatycznie stosowany do przywróconego koszyka.
Ustaw pole telefonu jako obowiązkowe w Ustawienia → Sklep → Logowanie / rejestracja, aby zmaksymalizować zasięg przypomnień.
### Podpisany link płatności i powiadomienia
Linki do checkoutu i odzyskania koszyka są podpisane HMAC SHA-256 z konfigurowalnym wygaśnięciem (domyślnie 72 h). Automatyczne powiadomienia: potwierdzenie zamówienia, wysyłka (z numerem śledzenia), nieudana płatność.
## Szablony HSM do utworzenia w Meta Business Suite
| Szablon | Zmienne treści | Przycisk |
| --- | --- | --- |
| Przypomnienie 1 i 2 | {{1}} imię klienta, {{2}} suma koszyka | Dynamiczny URL (sufiks = token) |
| Przypomnienie 3 | {{1}} imię, {{2}} suma, {{3}} kod promocyjny | Dynamiczny URL (sufiks = token) |
| Potwierdzenie | {{1}} imię, {{2}} nr zamówienia, {{3}} suma | — |
| Wysyłka | {{1}} imię, {{2}} nr zamówienia, {{3}} nr śledzenia | CTA śledzenia (opcjonalny) |
| Nieudana płatność | {{1}} imię, {{2}} nr zamówienia | CTA ponowienia (opcjonalny) |
W przypomnieniach przycisk URL szablonu musi mieć bazę `https://twojsklep.tld/df-wac/cart/restore?token=` z dynamicznym sufiksem `{{1}}`. Wpisz nazwy zatwierdzonych szablonów w konfiguracji wtyczki.
## Panel administracyjny
Marketing → WhatsApp Commerce: dashboard KPI (konwersacje, nieprzeczytane, koszyki, wskaźnik odzyskania, błędy), strona **Konwersacje** (wątek w stylu WhatsApp Web, bezpośrednia odpowiedź), **Porzucone koszyki**, **Katalog** (dziennik synchronizacji) oraz **Logi** (filtry poziomu/kanału).
Reguła Meta: swobodne odpowiedzi z panelu są dostarczane tylko w ciągu 24 h od ostatniej wiadomości klienta. Po tym czasie użyj szablonu HSM.
## Rozwiązywanie problemów
- **Nic nie widać w sklepie**: sprawdź, czy „Publiczny numer WhatsApp" jest ustawiony (pływający przycisk i CTA od niego zależą), potem `bin/console cache:clear`.
- **Webhook 403**: różny token weryfikacyjny między Meta a wtyczką, lub błędny App secret.
- **Przypomnienia nie są wysyłane**: sprawdź, czy `scheduled-task:run` i `messenger:consume` działają, czy moduł jest aktywny i czy szablony HSM są zatwierdzone.
- **Produkty nie są synchronizowane**: sprawdź stronę Katalog (statusy pending/synced/error) oraz Logi, kanał `catalog`.
## RODO
Żadne dane nie są wysyłane do podmiotów trzecich poza Meta WhatsApp Cloud API. Konwersacje i numery telefonów są przechowywane lokalnie w tabelach `df_wac_` i usuwane przy odinstalowaniu.