WhatsApp Commerce Suite: przewodnik instalacji i konfiguracji

Prezentacja

DataFirefly WhatsApp Commerce Suite zamienia WhatsAppa w pełnoprawny kanał sprzedaży dla WooCommerce przez oficjalne API Meta Cloud. Wtyczka obejmuje 4 moduły włączane niezależnie: synchronizację katalogu Meta Commerce, przyjmowanie zamówień w rozmowie, przypomnienia o porzuconym koszyku i podpisany link płatności.

Instalacja

1. Pobierz dfwhatsappcommerce-1.0.1.zip ze swojego konta klienta DataFirefly.
2. W wp-admin przejdź do Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer, wybierz ZIP i kliknij Zainstaluj teraz.
3. Włącz wtyczkę. W pasku bocznym administracji pojawia się nowe menu WhatsApp.

Przy aktywacji wtyczka tworzy 5 tabel SQL z przedrostkiem dfwc_ (rozmowy, wiadomości, porzucone koszyki, log katalogu, dzienniki) i planuje 3 zadania cron: przetwarzanie koszyków co 15 minut, codzienne czyszczenie logów i godzinną synchronizację katalogu partiami.

Wymagania po stronie Meta

Zanim skonfigurujesz wtyczkę, zbierz te 5 wartości z Meta Business Suite:

• Phone Number ID: WhatsApp → Konfiguracja API → Twój numer
• WhatsApp Business Account ID: widoczny w ustawieniach konta WhatsApp Business
• Catalog ID: Commerce Manager → Twój katalog → Ustawienia
• Trwały Access Token: utwórz użytkownika systemowego w Business Settings → Users → System Users, przypisz mu uprawnienia whatsapp_business_messaging i whatsapp_business_management oraz catalog_management, a następnie wygeneruj token bez wygaśnięcia
• App Secret: Meta for Developers → Twoja aplikacja → Ustawienia → Ogólne

Konfiguracja wtyczki

1. Przejdź do WhatsApp → Ustawienia.
2. W sekcji Dane dostępowe Meta Cloud API wklej 5 wartości zebranych powyżej. Pole Webhook Verify Token jest generowane automatycznie, zmieniaj je tylko w razie potrzeby.
3. Uzupełnij Wyświetlany numer WhatsApp w formacie E.164 bez znaku plus (przykład: 48612345678). To ten numer będzie używany dla pływającego przycisku i CTA.
4. Włącz wybrane moduły w sekcji Moduły. Możesz zacząć od samej synchronizacji katalogu i stopniowo włączać resztę.
5. Zapisz.

Konfiguracja webhooka Meta

Webhook pozwala Meta wysyłać do Twojej witryny wiadomości przychodzące i statusy dostarczenia.

1. Otwórz WhatsApp → Panel w wp-admin: Callback URL i Verify Token są tam wyświetlone z przyciskami Kopiuj.
2. W Meta for Developers otwórz swoją aplikację → WhatsApp → Konfiguracja → Webhook.
3. Wklej Callback URL i Verify Token, a następnie kliknij Zweryfikuj i zapisz.
4. Na liście pól zasubskrybuj messages.

Callback URL ma postać https://twoja-witryna.pl/wp-json/dfwc/v1/webhook. Każde żądanie przychodzące jest walidowane podpisem HMAC SHA-256 z Twoim App Secret: żądania niepodpisane albo źle podpisane są odrzucane.

Test połączenia

Z poziomu WhatsApp → Panel:

• Testuj połączenie API: weryfikuje dane dostępowe, odpytując Twój Phone Number ID, i wyświetla zweryfikowany numer.
• Wyślij wiadomość testową: wpisz numer w formacie E.164 bez plusa i wyślij testową wiadomość tekstową.

Moduł 1: synchronizacja katalogu

Trzy tryby dostępne w Ustawieniach:

• Czas rzeczywisty: każde utworzenie, zmiana, zmiana stanu magazynowego albo usunięcie produktu jest natychmiast odzwierciedlane w katalogu Meta.
• Partiami: zmiany są gromadzone i wypychane co godzinę partiami po 50.
• Ręcznie: nic nie jest wysyłane automatycznie, używasz przycisku ponownej synchronizacji.

Reguły mapowania:

• Każdy produkt otrzymuje retailer_id w postaci wc_{ID}.
• Produkty wariantowe nie są wysyłane jako całość: każdy wariant wypychany jest osobno, z własną ceną, stanem i obrazem.
• Produkty bez obrazu są pomijane (wymóg Meta).
• Filtr dfwc_catalog_product_eligible pozwala wykluczyć produkty kodem, a dfwc_catalog_product_data zmodyfikować wysyłane dane.

Od wersji 1.0.1 w Ustawienia → Synchronizacja katalogu dostępne są dwie listy kategorii: Kategorie do synchronizacji (zostaw puste, żeby wysyłać wszystko) i Kategorie wykluczone. Produkty bez obrazu są zapisywane w dzienniku ze statusem skipped, zamiast być ponownie wybierane przy każdej partii. W trybie czasu rzeczywistego każda synchronizacja trafia do kolejki Action Scheduler (dołączonego do WooCommerce): zapis produktu ani zmniejszenie stanu przy zamówieniu nigdy nie czeka na odpowiedź Meta. Zadania te znajdziesz w WooCommerce → Stan → Zaplanowane akcje, grupa dfwhatsappcommerce.

Strona WhatsApp → Katalog wyświetla liczniki sukcesów i błędów, dziennik 50 ostatnich zdarzeń oraz przycisk Uruchom ponowną synchronizację, który wypycha wszystkie kwalifikujące się produkty partiami po 100.

Moduł 2: zamówienia w rozmowie

Moduł rozmowy odpowiada automatycznie na wiadomości przychodzące według maszyny stanów: idle → browsing → selecting_qty → reviewing → awaiting_payment, plus stan human_handoff.

Rozpoznawane słowa kluczowe (francuski i angielski w tej samej rozmowie):

• menu albo catalogue: wyświetla interaktywną listę produktów (do 30 pozycji, połączonych z katalogiem Meta)
• panier albo cart: wyświetla zawartość koszyka z przyciskami Zapłać / Kontynuuj / Wyczyść
• commander, payer albo checkout: generuje link płatności
• humain, conseiller albo aide: przekazuje sprawę doradcy (e-mail wysyłany na skonfigurowany adres)
• reset albo annuler: resetuje rozmowę

Każdy inny tekst wyzwala swobodne wyszukiwanie wśród Twoich produktów. Koszyk klienta jest zachowywany w rozmowie i wiązany z jego kontem WooCommerce, jeśli numer odpowiada istniejącemu billing_phone.

Wiadomość powitalna i wiadomość zapasowa są konfigurowalne w Ustawieniach. Strona WhatsApp → Rozmowy wymienia wszystkie rozmowy i pozwala przeglądać każdy wątek w widoku podobnym do WhatsApp Web.

Moduł 3: przypomnienia o porzuconym koszyku

Działanie:

1. Wtyczka przechwytuje koszyk odwiedzających (sesja WooCommerce + zapasowe ciasteczko na 7 dni) i czyni pole telefonu obowiązkowym na checkoucie.
2. Po upływie czasu porzucenia (domyślnie 60 minut) wychodzi pierwsze przypomnienie. Przypomnienia 2 i 3 następują według własnych opóźnień (domyślnie 24 h i 72 h, wyrażone w minutach w Ustawieniach).
3. Każde przypomnienie używa szablonu HSM Meta skonfigurowanego per etap. Jeśli szablon zawiedzie, próbowana jest zwykła wiadomość tekstowa jako zapas.
4. Trzecie przypomnienie może dołączyć istniejący kod rabatowy WooCommerce, stosowany automatycznie na checkoucie przez link odzyskiwania.
5. Gdy klient sfinalizuje zamówienie, koszyk zostaje oznaczony jako odzyskany, a przypomnienia się zatrzymują.

Tworzenie szablonów HSM

W Meta Business Suite → WhatsApp Manager → Szablony wiadomości utwórz 3 szablony (na przykład dfwc_abandoned_cart_1, _2, _3) z:

• Treścią zawierającą dwie zmienne: {{1}} = imię klienta, {{2}} = kwota koszyka
• Przyciskiem akcji typu URL ze zmienną {{1}} na końcu adresu, wskazującym na https://twoja-witryna.pl/wp-json/dfwc/v1/recover/{{1}}

Utwórz każdy szablon w językach swoich klientów: wtyczka wykrywa locale i wysyła właściwą wersję. Po zatwierdzeniu szablonów przez Meta wpisz ich nazwy w Ustawieniach wtyczki.

Strona WhatsApp → Porzucone koszyki pokazuje sumę, koszyki w trakcie przypominania, koszyki odzyskane i wskaźnik odzyskiwania.

Moduł 4: płatność i powiadomienia

Link płatności generowany w rozmowie to token podpisany HMAC (SHA-256, sól WordPressa + sekret wtyczki) zawierający koszyk, datę wygaśnięcia i identyfikator rozmowy. Gdy klient kliknie:

1. Token jest walidowany i dekodowany.
2. Koszyk WooCommerce jest odtwarzany po stronie serwera.
3. Telefon klienta jest wstępnie wypełniany na checkoucie.
4. Adres URL jest czyszczony przez przekierowanie.

Czas ważności linku jest konfigurowalny (Ustawienia → Płatność). Wygasły link wyświetla komunikat błędu z zachętą do poproszenia o nowy przez WhatsAppa.

Automatyczne powiadomienia (włączane pojedynczo):

• Zamówienie potwierdzone: wysyłane przy przejściu w status Processing, z numerem i sumą.
• Zamówienie wysłane: wysyłane przy przejściu w Completed, z numerem śledzenia wykrytym z Shipment Tracking, AfterShip albo meta _tracking_number, oraz przyciskiem CTA do śledzenia.
• Płatność nieudana: wysyłane przy przejściu w Failed, z przyciskiem ponowienia płatności.

Przycisk pływający i CTA

• Przycisk pływający: włączany w Ustawieniach, pozycja do wyboru spośród 4 narożników, konfigurowalna etykieta, możliwość ukrycia. Szablon templates/frontend/whatsapp-button.php można nadpisać, kopiując go do twoj-motyw/dfwhatsappcommerce/whatsapp-button.php.
• CTA na karcie produktu: przycisk „Zamów przez WhatsAppa” pod przyciskiem dodania do koszyka, z wiadomością wstępnie wypełnioną nazwą i linkiem produktu.
• CTA w koszyku: przycisk „Sfinalizuj przez WhatsAppa” z sumą koszyka.
• CTA na checkoucie: dyskretny link pomocy.
• Shortcode: [dfwc_whatsapp_button text="..." message="..."] do ręcznego umieszczenia w dowolnym miejscu.

Kliknięcia we wszystkie te elementy są wypychane do dataLayer (przedrostek dfwc_) dla GA4 i Google Tag Managera.

Dzienniki i rozwiązywanie problemów

Strona WhatsApp → Dzienniki wyświetla wszystkie zdarzenia z filtrami po poziomie (debug do critical) i po kanale (api, webhook, catalog, conversation, cart, payment). Poziom logowania i okres retencji są konfigurowalne. Logi widać też w WooCommerce → Status → Dzienniki, pod źródłami dfwhatsappcommerce-*.

Częste problemy:

• Webhook się nie weryfikuje: sprawdź, czy witryna działa po HTTPS z ważnym certyfikatem, czy bezpośrednie odnośniki nie są w trybie „Prosty” i czy Verify Token wklejony u Meta jest identyczny z tym z Ustawień.
• Wiadomości przychodzące nie docierają: sprawdź, czy pole messages jest zasubskrybowane w konfiguracji webhooka Meta i czy App Secret jest poprawny (nieprawidłowy podpis powoduje ciche odrzucenie żądań, widoczne w Dziennikach, kanał webhook).
• Synchronizacja katalogu zawodzi: sprawdź, czy token systemowy ma uprawnienie catalog_management i czy Catalog ID odpowiada katalogowi powiązanemu z Twoim kontem WhatsApp Business.
• Przypomnienia nie wychodzą: sprawdź, czy cron WordPressa działa (WP Crontrol pozwala podejrzeć dfwc_process_abandoned_carts) i czy szablony HSM są zatwierdzone przez Meta.

Deinstalacja

Wyłączenie wtyczki zachowuje wszystkie dane. Trwałe usunięcie ze strony Wtyczki uruchamia uninstall.php: 5 tabel zostaje usuniętych, opcje i zadania cron skasowane. Zamówienia WooCommerce utworzone przez WhatsAppa nigdy nie są ruszane.