WhatsApp

Agenta Leezy można połączyć z numerem WhatsApp Business, żeby klienci rozmawiali z AI bezpośrednio w WhatsAppie.

Ten przewodnik prowadzi przez całą konfigurację, łącznie z częścią po stronie Meta. Konfiguracja jest jednorazowa i przy pierwszym podejściu zajmuje około 30–45 minut. Jeśli potrzebna będzie weryfikacja firmy, zajmie więcej czasu.

Jak to działa

Po połączeniu każda wiadomość wysłana na numer WhatsApp trafia do Leezy, agent tworzy odpowiedź na podstawie swojej wiedzy, a odpowiedź wraca przez WhatsAppa. Rozmowy pojawiają się obok czatów z witryny w zakładce Activity.

Integracja korzysta z oficjalnego WhatsApp Cloud API firmy Meta, więc dostarczanie wiadomości, szyfrowanie i dostępność leżą po stronie Meta.

Do kogo należy aplikacja Meta

Aplikacja Meta utworzona w trakcie konfiguracji należy do firmy, która ją zakłada, a nie do Leezy. Leezy nie jest dostawcą rozwiązań WhatsApp — każda firma prowadzi własną aplikację Meta i podłącza własne dane dostępowe. Wynika z tego kilka rzeczy:

• Nie jest wymagana weryfikacja ani zatwierdzenie przez Meta. Aplikacja może pozostać w trybie Development w portalu deweloperskim — to normalny stan przy Cloud API i nie blokuje wysyłania ani odbierania prawdziwych wiadomości.
• Weryfikacja firmy w Meta jest na start opcjonalna. Podnosi limit 250 rozmów dziennie i odblokowuje wiadomości marketingowe oraz szablonowe, ale nie jest warunkiem połączenia z Leezy.
• Tymczasowy token dostępu pokazany zaraz po utworzeniu aplikacji wygasa po 24 godzinach. Do realnego użycia służy stały token System User (faza 3).

Krótko: rejestracja w Meta i przejście przez cztery poniższe fazy wystarczą. Bez przeglądu platformy, bez zgłaszania aplikacji, bez czekania w kolejce akceptacyjnej.

Kto za co płaci

Są dwa niezależne strumienie kosztów — warto poznać oba przed połączeniem:

Koszt	Odbiorca	Uwagi
Opłaty za rozmowy WhatsApp (za sesję wiadomości)	Meta, rozliczane z firmą będącą właścicielem konta WhatsApp Business	Ceny zależą od kraju i kategorii rozmowy (serwisowa, marketingowa, użytkowa, uwierzytelniająca). Większość rozmów serwisowych mieści się między 0,005 a 0,08 USD. Zobacz cennik Meta.
Generowanie odpowiedzi AI	Leezy, odejmowane od limitu planu przestrzeni roboczej	Każda wymiana na WhatsAppie kosztuje 2 jednostki wiadomości (1 przychodząca + 1 odpowiedź AI), dokładnie jak w widżecie na stronie.

Krótko: klient Leezy jest właścicielem aplikacji Meta i płaci Meta za dostarczanie wiadomości; Leezy pokrywa koszt AI i zlicza każdą wymianę do limitu planu.

Wymagania

• Płatny plan przestrzeni roboczej w Leezy. WhatsAppa mogą połączyć role owner i admin.
• Włączona funkcja beta Integrations dla przestrzeni roboczej. Bez niej WhatsApp nie pojawia się wśród kanałów wdrożenia.
• Konto na Facebooku z dostępem do konta Meta Business albo z prawem do jego utworzenia.
• Numer telefonu, który nie jest zarejestrowany w WhatsAppie (ani w aplikacji zwykłej, ani w WhatsApp Business). Numer musi móc odebrać SMS lub połączenie weryfikacyjne.
• Karta płatnicza dodana w Meta Business Manager (Meta wymaga jej przed wysyłką produkcyjną, nawet przy małych wolumenach).

:::tip Tryb testowy jest darmowy Meta udostępnia darmowy testowy numer telefonu, który bez weryfikacji firmy może pisać do maksymalnie pięciu wcześniej zatwierdzonych odbiorców. Cały proces działa z tym numerem, więc integrację można w pełni sprawdzić przed dodaniem płatności i prawdziwego numeru. :::

Przegląd konfiguracji

Konfiguracja obejmuje cztery miejsca:

1. Meta Business Manager — kontener na poziomie firmy.
2. Meta for Developers — tu żyje aplikacja Meta rozmawiająca z Leezy.
3. Meta Business Settings → System Users — tu powstaje stały token dostępu.
4. Leezy — tu wklejasz wszystkie wartości i kopiujesz adres webhooka z powrotem do Meta.

Każda faza kończy się listą wartości do zapisania. Po fazie 3 powinny być zapisane cztery wartości; faza 4 z nich korzysta.

---

Faza 1 — konto Meta Business

Konto Meta Business to formalna otoczka połączenia z WhatsAppem. Jego założenie jest bezpłatne.

1.1 Utwórz lub otwórz konto Business

1. Wejdź na business.facebook.com i zaloguj się kontem Facebooka, do którego ma należeć połączenie.
2. Jeśli nie masz jeszcze konta Business, kliknij Utwórz konto i podaj nazwę firmy, osobę zarządzającą i firmowy adres e-mail.
3. Jeśli konto już istnieje, po prostu je otwórz.

1.2 Zapisz identyfikator konta Business

Ten identyfikator bywa potrzebny przy zgłoszeniach do wsparcia. Znajdziesz go, klikając ikonę koła zębatego (⚙️) w lewym dolnym rogu → Ustawienia firmy; identyfikator jest na górze pod nazwą firmy.

:::note Weryfikacja firmy Meta ogranicza niezweryfikowane firmy do 250 unikalnych rozmów z klientami na 24 godziny. Weryfikacja nie jest potrzebna na start, ale zaplanuj ją przed kampanią marketingową. Trwa 1–3 dni robocze i wymaga dokumentu firmowego (wpis do rejestru, rachunek za media albo dokument podatkowy). Uruchomisz ją w Ustawienia firmy → Centrum bezpieczeństwa → Rozpocznij weryfikację. :::

---

Faza 2 — utwórz aplikację Meta z WhatsAppem

Aplikacja Meta przechowuje dane dostępowe WhatsApp Cloud API.

2.1 Utwórz aplikację

Meta prowadzi przez pięć kroków: Szczegóły aplikacji → Przypadki użycia → Firma → Wymagania → Podsumowanie.

1. Wejdź na developers.facebook.com i zaloguj się tym samym kontem Facebooka.
2. Kliknij My Apps w prawym górnym rogu, a potem Create app.
3. Szczegóły aplikacji: podaj nazwę wyświetlaną (np. „Acme Obsługa Klienta") i adres kontaktowy. Kliknij Next.
4. Przypadki użycia: wybierz przypadek związany z WhatsAppem (albo „Other", jeśli taki widzisz). Kliknij Next.
5. Firma: podepnij konto Business z fazy 1. Kliknij Next.
6. Wymagania / Podsumowanie: sprawdź dane, kliknij Create app i przejdź test bezpieczeństwa.

:::note Kreator bywa zmieniany Meta regularnie przebudowuje ten proces, więc nazwy kroków mogą się różnić. Liczy się efekt: po utworzeniu trafiasz na App Dashboard z menu bocznym zawierającym Dashboard, App Settings, App Roles, Notifications, App Review, Products, Webhooks. :::

:::tip Tryb „Development" to stan normalny Po utworzeniu aplikacji panel deweloperski pokazuje ją jako In Development i może wyświetlić baner o App Review. Jedno i drugie jest normalne i niczego nie blokuje. Wysyłka i odbiór przez Cloud API działa w trybie Development — bez App Review i bez przełączania aplikacji na „Live". :::

2.2 Dodaj produkt WhatsApp

1. W panelu nowej aplikacji przewiń do Add products to your app.
2. Na karcie WhatsApp kliknij Set up.
3. Meta automatycznie tworzy testowe konto WhatsApp Business (WABA) i testowy numer. To normalne — numer testowy można później zastąpić.
4. Pojawi się ekran API Setup. Zostaw tę kartę otwartą — większość wartości potrzebnych w fazie 3 pochodzi właśnie stąd.

2.3 Skopiuj Phone Number ID i WABA ID

Na stronie API Setup:

1. Lista From pokazuje wszystkie numery przypisane do aplikacji. Bezpośrednio pod nią widnieje Phone number ID (15–17 cyfr). Skopiuj tę wartość — to phone_number_id.
2. Niżej znajdziesz WhatsApp Business Account ID. Skopiuj tę wartość — to waba_id.

:::caution Numer testowy a produkcyjny Phone Number ID automatycznie utworzonego numeru testowego nadaje się do testów, ale pozwala pisać tylko do pięciu wcześniej zatwierdzonych odbiorców (dodawanych w polu To na tej samej stronie). Aby ruszyć produkcyjnie, kliknij Add phone number i przejdź weryfikację numeru, który nie jest zarejestrowany w WhatsAppie. :::

2.4 Skopiuj App Secret

App Secret służy do potwierdzania, że przychodzące żądania webhooka faktycznie pochodzą od Meta.

1. W menu bocznym otwórz App Settings → Basic.
2. Przy polu App Secret kliknij Show, wpisz hasło do Facebooka, jeśli pojawi się prośba, i skopiuj wartość. To app_secret.

:::warning Traktuj App Secret jak hasło To długowieczny klucz podpisujący. Kto go ma, może podrobić żądania webhooka. Leezy przechowuje go zaszyfrowanego, ale nigdy nie wysyłaj go na czacie, mailem ani na zrzutach ekranu. :::

Lista kontrolna fazy 2

• phone_number_id
• waba_id
• app_secret

---

Faza 3 — wygeneruj stały token dostępu

Token dostępu upoważnia Leezy do wysyłania wiadomości w imieniu numeru WhatsApp. Tymczasowy token z ekranu API Setup wygasa po 24 godzinach, więc do realnego użycia potrzebny jest token System User.

3.1 Utwórz System User

1. Otwórz Meta Business Settings.
2. W menu bocznym wybierz Users → System users.
3. Kliknij Add, nadaj nazwę (np. „Leezy Integration"), ustaw rolę Admin i kliknij Create system user.

3.2 Przypisz konto WhatsApp Business

1. Przy zaznaczonym System User kliknij Add assets.
2. Wybierz WhatsApp accounts, zaznacz WABA z fazy 2 i nadaj Full control.
3. Kliknij Save changes.

3.3 Wygeneruj token dostępu

1. Na stronie System User kliknij Generate new token.
2. Kreator ma cztery kroki:
   • Wybór aplikacji: wskaż aplikację Meta z fazy 2.
   • Ważność tokenu: wybierz Never. Domyślnie zaznaczone jest „60 dni (zalecane)" — patrz ostrzeżenie niżej.
   • Uprawnienia: trzy zakresy WhatsAppa są zaznaczone automatycznie:
     • whatsapp_business_messaging
     • whatsapp_business_management
     • whatsapp_business_manage_events Zostaw wszystkie trzy zaznaczone.
3. Kliknij Generate token.
4. Skopiuj token od razu. To access_token. Nie zostanie pokazany ponownie — jeśli go zgubisz, wygeneruj nowy.

:::warning 60 dni czy „Never" Meta zaleca dziś rotację tokenów co 60 dni i domyślnie zaznacza tę opcję. Wybór Never utrzyma integrację bez rotacji, ale odbiega od zalecenia Meta. W środowiskach o wysokich wymaganiach bezpieczeństwa wybierz 60 dni i ustaw przypomnienie, aby wygenerować nowy token i zaktualizować go w Leezy przed wygaśnięciem. Dla większości zespołów Never jest rozsądnym kompromisem. :::

:::warning Przechowywanie tokenu Token daje pełne prawa do wysyłania i odbierania na tym numerze. Podobnie jak App Secret, Leezy przechowuje go zaszyfrowanego. Nie wklejaj go do współdzielonych dokumentów. :::

Lista kontrolna fazy 3

• phone_number_id
• waba_id
• app_secret
• access_token

---

Faza 4 — połącz w Leezy

4.1 Otwórz ekran łączenia WhatsAppa

1. W Leezy otwórz agenta, który ma odpowiadać na WhatsAppie.
2. Przejdź do Deploy → WhatsApp.
3. Kliknij Connect WhatsApp.

4.2 Wklej cztery wartości

Pole w Leezy	Wartość z Meta
Phone Number ID	phone_number_id (faza 2.3)
WhatsApp Business Account ID	waba_id (faza 2.3)
Access Token	access_token (faza 3.3)
App Secret	app_secret (faza 2.4)

Kliknij Connect. Leezy zweryfikuje dane w Meta, zapisze je w formie zaszyfrowanej i pokaże adres webhooka oraz Verify Token. Skopiuj oba — będą potrzebne w kolejnym kroku.

4.3 Skonfiguruj webhook w Meta

Ten krok mówi Meta, dokąd wysyłać przychodzące wiadomości. Wszystko dzieje się na jednej stronie; nie ma osobnego okna edycji.

1. Wróć do aplikacji Meta na developers.facebook.com → WhatsApp → Configuration.
2. W sekcji Webhook na górze strony:
   • wklej adres webhooka z Leezy w pole Callback URL,
   • wklej Verify Token z Leezy w pole Verify token,
   • kliknij Verify and save. Meta wyśle jednorazowe żądanie weryfikacyjne i przy powodzeniu pokaże zielone potwierdzenie.
3. Poniżej znajduje się tabela Webhook fields ze wszystkimi zdarzeniami, o których Meta może informować. W wierszu messages przestaw przełącznik na Subscribed. Pozostałe pola zostaw wyłączone.

:::tip Najpierw weryfikacja, potem subskrypcja Przełącznik zostanie włączony tylko wtedy, gdy Callback URL został wcześniej poprawnie zweryfikowany. Jeśli przełącznik nie chce się utrzymać, sprawdź ponownie adres i Verify Token z kroku 2. :::

4.4 Wyślij wiadomość testową

Napisz z prywatnego konta WhatsApp na numer produkcyjny — albo, jeśli korzystasz z numeru testowego, najpierw dodaj swój numer do listy To na stronie API Setup, a potem wyślij wiadomość.

W ciągu kilku sekund powinna przyjść odpowiedź AI. Rozmowa pojawi się też w zakładce Activity agenta.

Jeśli nic nie przychodzi, zajrzyj do sekcji Rozwiązywanie problemów.

---

Co agent potrafi dziś

Funkcja	Status
Odpowiadanie na przychodzące wiadomości tekstowe	✅ obsługiwane
Korzystanie z wytrenowanej wiedzy (RAG)	✅ obsługiwane
Uruchamianie narzędzi AI (pozyskanie leada, zgłoszenie)	✅ obsługiwane
Odbiór obrazów, dokumentów, wiadomości głosowych	Potwierdzane tekstem zastępczym; pełna obsługa mediów jest w planach
Wysyłanie obrazów, dokumentów i przycisków	Jeszcze nieobsługiwane w wersji 1
Wiadomości wychodzące poza oknem 24 godzin	Jeszcze nieobsługiwane — wymaga szablonów zatwierdzonych przez Meta

Okno serwisowe 24 godzin

Meta zezwala na swobodne wiadomości tylko w ciągu 24 godzin od ostatniej wiadomości klienta. Po tym czasie można wysyłać wyłącznie zatwierdzone szablony. Ponieważ Leezy w wersji 1 wyłącznie odpowiada, reguła ta pozostaje niewidoczna: każda odpowiedź następuje bezpośrednio po wiadomości klienta, czyli zawsze w oknie.

Rozwiązywanie problemów

„Verify and save" kończy się błędem

• Sprawdź, czy Verify Token został wklejony dokładnie, bez spacji na początku i końcu.
• Sprawdź, czy Callback URL skopiowano w całości (kończy się na /api/webhooks/whatsapp).
• Połączenie w Leezy musi być nadal aktywne — po ponownym otwarciu ekranu łączenia przycisk Reconnect generuje świeży Verify Token.

Wiadomości wychodzą, ale odpowiedź nie przychodzi

• Sprawdź, czy pole webhooka messages jest zasubskrybowane w Meta (faza 4.3). To najczęstsza przyczyna.
• Zajrzyj do zakładki Activity w Leezy — jeśli wiadomość przychodząca tam jest, a odpowiedzi brak, prawdopodobnie wyczerpał się limit planu.
• Przy numerach testowych numer nadawcy musi być na liście To na stronie API Setup, inaczej Meta odrzuci wiadomość przed dotarciem do Leezy.

Błąd „Invalid OAuth access token" przy łączeniu

• Prawdopodobnie użyto tymczasowego tokenu ze strony API Setup (ważny 24 godziny). Wygeneruj stały token System User zgodnie z fazą 3.
• Sprawdź, czy przy generowaniu zaznaczono zarówno whatsapp_business_messaging, jak i whatsapp_business_management.

Odpowiedzi są wolne albo w złej kolejności

• Meta stosuje limit tempa na numer. Bez weryfikacji jest to 250 unikalnych rozmów na 24 godziny; po przekroczeniu Meta zaczyna odrzucać wysyłki.
• Weryfikacja firmy (faza 1.2) podnosi ten limit.

Rozłączenie WhatsAppa

W Leezy przejdź do Deploy → WhatsApp → Disconnect. Dane dostępowe zostaną usunięte, a webhook wyrejestrowany. Aplikacja Meta i numer telefonu pozostają nienaruszone i można je połączyć ponownie.

Aby całkowicie usunąć konto WhatsApp Business po stronie Meta, zrób to w Ustawienia firmy → Konta → Konta WhatsApp.

Najczęstsze pytania

Czy ten sam numer WhatsApp może działać jednocześnie z innym narzędziem? Nie. Numer WhatsApp Business może być podłączony tylko do jednej integracji Cloud API naraz. Najpierw rozłącz poprzednie narzędzie.

Czy kilku agentów może dzielić jeden numer WhatsApp? Nie. Każdy numer odpowiada dokładnie jednemu agentowi. Aby uruchomić kilku agentów, zarejestruj w Meta kilka numerów.

Czy Leezy przechowuje treść wiadomości? Tak — w obie strony, w historii rozmów agenta, tak samo jak czaty z witryny. Są widoczne w zakładce Activity i liczą się do limitu planu.

Gdzie przechowywane są dane? Wszystkie dane rozmów są przechowywane w UE.

Co się stanie, gdy aplikacja Meta zostanie usunięta albo token cofnięty? Wiadomości przychodzące przestaną docierać do Leezy, a odpowiedzi nie będą wychodzić. Połączenie zgłosi błąd przy kolejnej próbie. Wygeneruj nowy token i kliknij Reconnect w Leezy.

Czy aplikacja Meta wymaga przeglądu lub zatwierdzenia przez Meta? Nie. Aplikacja pozostaje w trybie Development i to właściwy stan dla Cloud API. Osobny proces App Review dotyczy dostępu do kont innych firm i nie jest tu potrzebny.

Czy weryfikacja firmy w Meta jest wymagana? Nie na start. Niezweryfikowane konta obsłużą do 250 unikalnych rozmów na 24 godziny, co wystarcza do testów i małych wdrożeń. Weryfikacja podnosi ten limit i umożliwia wiadomości marketingowe oraz szablonowe.

Czy Leezy jest dostawcą rozwiązań WhatsApp zatwierdzonym przez Meta? Nie, i integracja tego nie wymaga. Każda firma podłącza własną aplikację Meta i własne dane dostępowe, więc połączenie z WhatsAppem istnieje bezpośrednio między firmą a Meta — Leezy dokłada warstwę agenta.