SW Shopware 6 Shopware Średnio zaawansowany

WhatsApp Commerce Suite Shopware — przewodnik instalacji i konfiguracji

Instalacja wtyczki, połączenie z Meta Cloud API, konfiguracja webhooka, szablonów HSM i 4 modułów w Shopware 6.5, 6.6 i 6.7.

Zaktualizowano Wersja modułu 1.0.0

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

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.

Czy ta strona była pomocna?

Nadal utknąłeś? Napisz do wsparcia