# WhatsApp

Integracja WhatsApp z Ritevo: podłączenie numeru WhatsApp Business przez Meta, PIN weryfikacji, wiadomości od klientów na żywo i odpowiadanie na nie.

Integracja WhatsApp podłącza do Ritevo numer WhatsApp Business. Wiadomości od klientów trafiają do wspólnej skrzynki **Wiadomości** od razu, gdy klient je wyśle, i stamtąd na nie odpowiadasz.

> **Wymagana integracja:** Potrzebujesz konta na Facebooku z dostępem do konta firmowego Meta i numeru telefonu, który podłączysz jako WhatsApp Business. Konto WhatsApp Business i numer możesz utworzyć w trakcie podłączania.

Jedna integracja to jeden numer - okno Meta zawsze kończy się wyborem jednego numeru. Kilka numerów podłączasz po kolei, każdy jako osobną integrację.

W ramach jednego konta firmowego dany numer podłączysz tylko raz: gdy Ty albo ktoś z Twoich współpracowników podłączy go ponownie, odświeży się istniejąca integracja - także wtedy, gdy wcześniej została usunięta - a druga nie powstanie.

Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `WHATSAPP`. Ponowne utworzenie odświeża istniejącą integrację zamiast tworzyć nową: od razu ustawia `authError=false`, a jeśli integracja była nieaktywna - także `active=true`. Przy `authError` to jedyny sposób na przywrócenie połączenia.

WhatsApp podłączasz przez okno logowania Facebooka. Nie podajesz nam hasła - Meta przekazuje tylko ten dostęp, na który zgodzisz się w tym oknie.

## PIN weryfikacji dwuetapowej

Przy podłączaniu wpisujesz 6-cyfrowy PIN weryfikacji dwuetapowej numeru. Meta wymaga go przy rejestracji numeru do wysyłania wiadomości:

- **Numer bez PIN-u** - wpisz nowy PIN; zostanie ustawiony dla tego numeru. Zapisz go, przyda się przy ponownym podłączeniu.
- **Numer z PIN-em** - wpisz ten sam PIN, który numer już ma. Inny PIN Meta odrzuci.
- **Nie pamiętasz PIN-u** - zresetuj weryfikację dwuetapową numeru w panelu Meta i wpisz nowy PIN przy podłączaniu.

## Podłączenie konta

Zacznij od listy integracji:

1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu.
2. W sekcji **Komunikatory** wybierz kafelek **WhatsApp**.
3. W polu **PIN weryfikacyjny (6 cyfr)** wpisz PIN numeru - opis wyżej.
4. Kliknij **Połącz WhatsApp**. Otworzy się okno Meta.
5. W oknie Meta postępuj według kroków: zaloguj się, wybierz albo utwórz konto WhatsApp Business, wybierz albo dodaj numer telefonu i potwierdź udostępnienie danych przyciskiem **Kontynuuj**.
6. Wróć do okna z integracjami. Sprawdzamy w Meta, czy masz dostęp do wybranego konta i numeru, podłączamy numer do odbierania wiadomości i otwieramy ustawienia nowej integracji. Jeśli coś się nie zgadza, zobaczysz błąd zwrócony przez Meta i nic nie zostanie zapisane.

![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp)

![Ekran dodawania integracji WhatsApp z polem PIN weryfikacyjny (6 cyfr), podpowiedzią o PIN-ie i przyciskiem Połącz WhatsApp](https://ritevo.com/docs/integrations/whatsapp/pl-add.webp)

![Okno logowania do Facebooka dla firm z opisem połączenia konta WhatsApp Business i przyciskiem Kontynuuj](https://ritevo.com/docs/integrations/whatsapp/pl-meta.webp)

> **Warto wiedzieć:** Jeśli okno Facebooka zostanie białe albo się zawiesi, zamknij je i kliknij przycisk połączenia jeszcze raz - to błąd po stronie Facebooka. Potem postępuj według kroków w oknie Facebooka.

## Ustawienia integracji

Integracja od razu jest **Aktywna** i odbiera wiadomości - nie ma tu przełącznika pobierania, bo WhatsApp przekazuje wiadomości na bieżąco. Na stronie integracji znajdziesz, tylko do odczytu:

- **Nazwa konta** - podłączony numer telefonu.
- **Identyfikator WABA** - identyfikator konta WhatsApp Business w Meta.
- **Identyfikator numeru telefonu** - identyfikator numeru w Meta.

![Szczegóły integracji WhatsApp: nazwa konta, identyfikator WABA i identyfikator numeru telefonu, tylko do odczytu](https://ritevo.com/docs/integrations/whatsapp/pl-details.webp)

![Sekcja Komunikatory na liście integracji z kafelkami WhatsApp i Messenger oznaczonymi jako Aktywna](https://ritevo.com/docs/integrations/whatsapp/pl-list.webp)

## Wiadomości z WhatsAppa

- **Historia rozmów** - WhatsApp nie udostępnia historii, więc wiadomości i załączniki zapisujemy u siebie od chwili podłączenia. Masz do nich dostęp także wtedy, gdy integracja wymaga ponownego połączenia - bez połączenia nie wyślesz tylko odpowiedzi.
- **Na żywo** - wiadomość od klienta pojawia się w skrzynce od razu, bez czekania na kolejne sprawdzenie.
- **Wątki** - każda rozmowa z jednym numerem klienta to jeden wątek typu **Wiadomość**. Nie jest automatycznie łączony z zamówieniem.
- **Odpowiedzi z innych programów** - jeśli na tym numerze odpisujesz klientom także z innego programu, w wątku zobaczysz tylko, że o tej godzinie wysłano wiadomość - bez jej treści. To ograniczenie WhatsAppa: nie przekazuje treści wiadomości wysłanych z innych programów. Żeby mieć całą rozmowę, odpowiadaj klientom tylko w Ritevo.

## Odpowiadanie klientom

- **Od razu w wątku** - wysłaną odpowiedź widać w wątku od razu, a jej status zmienia się, gdy WhatsApp potwierdzi dostarczenie.
- **24 godziny** - WhatsApp pozwala odpowiadać swobodnie przez 24 godziny od ostatniej wiadomości klienta. Później odrzuci zwykłą odpowiedź i zobaczysz błąd. Po tym czasie rozmowę można zacząć tylko zatwierdzonym szablonem WhatsApp - takich szablonów jeszcze nie wysyłamy, więc napiszesz dopiero, gdy klient odezwie się pierwszy.

## Wymaga ponownego połączenia

Ten stan pojawia się, gdy Meta przestała akceptować nasz dostęp do numeru - na przykład po odebraniu uprawnień aplikacji w ustawieniach konta firmowego Meta. Do czasu ponownego połączenia nie wyślesz odpowiedzi z tego numeru.

1. Przejdź przez **Podłączenie konta** jeszcze raz i wybierz w oknie Meta **ten sam** numer.
2. Wpisz **ten sam PIN**, który numer już ma. Połączenie odświeży się w istniejącej integracji - historia zostaje, druga integracja nie powstanie.

> **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać.

W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony.

## Usunięcie integracji

**Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem.

## Czego integracja nie robi

- Nie pobiera rozmów sprzed podłączenia numeru.
- Nie wysyła zatwierdzonych szablonów WhatsApp, więc nie zacznie rozmowy po upływie 24 godzin.
- Nie pokazuje treści wiadomości wysłanych z innego programu podłączonego do tego numeru.

## Integracja WhatsApp przez API (dla AI i integratorów)

Ta sekcja istnieje tylko w wersji Markdown. Integracja ma typ `MESSAGING` i dostawcę `WHATSAPP`. Podłączenie wymaga okna Meta (Embedded Signup) w przeglądarce, więc samo API nie utworzy integracji bez udziału człowieka.

- `POST /integrations/messaging/whatsapp` - utworzenie integracji z wyniku okna Meta: `code` (jednorazowy kod autoryzacji), `wabaId`, `phoneNumberId` i `verificationPin` (6 cyfr). Backend sprawdza w Meta, że kod daje dostęp do tego konta i numeru; ponowne podłączenie tego samego numeru odświeża istniejącą integrację.
- `GET /integrations/messaging/{integrationId}` - integracja: `accountName` (numer), `externalId` (`wabaId::-::phoneNumberId`), `phoneNumberId`, `displayPhoneNumber`, `active`, `authError` (true = **Wymaga ponownego połączenia**). Bez tokenu dostępu.
- `DELETE /integrations/messaging/{integrationId}` - **Usuń integrację**, `PATCH /integrations/messaging/{integrationId}/restore` - **Przywróć integrację**.
- Wątki mają `threadType` = `MESSAGE` i nie mają powiązanego zamówienia. Odpowiedź wysyłasz tak samo jak w innych kanałach.

Endpointy tej integracji są pod `/integrations/messaging/whatsapp`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/messaging`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs.

Odłączenie aplikacji po stronie Meta: Meta nie powiadamia Ritevo o odebraniu dostępu. Nowe wiadomości przestają wtedy przychodzić, a integracja dostaje `authError=true` przy pierwszym zapytaniu do Meta, na przykład przy próbie wysłania odpowiedzi. Zapisana historia rozmów zostaje.


---

Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.