# Messenger

Integracja Messenger z Ritevo: podłączenie strony na Facebooku, wiadomości od klientów na żywo, odpowiadanie, załączniki i ponowne połączenie.

Integracja Messenger podłącza do Ritevo stronę na Facebooku. Wiadomości, które klienci wysyłają do strony przez Messengera, trafiają do wspólnej skrzynki **Wiadomości** od razu, i stamtąd na nie odpowiadasz.

> **Wymagana integracja:** Potrzebujesz strony na Facebooku i konta, które ma do niej pełny dostęp.

Jedna integracja to jedna strona. W oknie Facebooka zaznacz dokładnie **jedną** stronę - jeśli zaznaczysz kilka, zobaczysz błąd i nic nie zostanie zapisane. Kilka stron podłączasz po kolei, każdą jako osobną integrację.

W ramach jednego konta firmowego daną stronę podłączysz tylko raz: gdy Ty albo ktoś z Twoich współpracowników podłączy ją 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 `MESSENGER`. 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.

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

## 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 **Messenger**.
3. Kliknij **Połącz z Facebookiem**. Otworzy się okno Facebooka.
4. Zaloguj się i zaznacz **jedną** stronę, którą chcesz podłączyć. Jeśli łączyłeś już wcześniej konto z Facebookiem, okno zapyta, czy kontynuować z wcześniejszymi ustawieniami - kliknij **Edytuj ustawienia**, żeby wybrać inną stronę, albo **Kontynuuj**.
5. Wróć do okna z integracjami i chwilę poczekaj - nie zamykaj go. Podłączamy stronę do odbierania wiadomości i otwieramy ustawienia nowej integracji. Jeśli coś się nie uda, zobaczysz błąd zwrócony przez Facebooka 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 Messenger z informacją o wyborze jednej strony i przyciskiem Połącz z Facebookiem](https://ritevo.com/docs/integrations/messenger/pl-add.webp)

![Okno logowania do Facebooka dla firm z pytaniem, czy kontynuować z wcześniejszymi ustawieniami, i przyciskami Edytuj ustawienia oraz Kontynuuj](https://ritevo.com/docs/integrations/messenger/pl-facebook.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 Messenger przekazuje wiadomości na bieżąco. Na stronie integracji znajdziesz, tylko do odczytu:

- **Nazwa strony** - nazwa podłączonej strony na Facebooku.
- **Identyfikator strony** - identyfikator strony w Facebooku.

![Szczegóły integracji Messenger: nazwa strony i identyfikator strony, tylko do odczytu](https://ritevo.com/docs/integrations/messenger/pl-details.webp)

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

## Wiadomości z Messengera

- **Historia rozmów** - Messenger 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 jedną osobą to jeden wątek typu **Wiadomość**, podpisany imieniem i nazwiskiem z jej profilu. Nie jest automatycznie łączony z zamówieniem.
- **Przyciski strony** - gdy klient zamiast pisać kliknie przycisk ustawiony na Twojej stronie w Messengerze (na przykład „Rozpocznij" albo pozycję menu), w wątku zobaczysz wiadomość z nazwą tego przycisku.

## Odpowiadanie klientom

- **Od razu w wątku** - wysłaną odpowiedź widać w wątku od razu, a jej status zmienia się, gdy Messenger potwierdzi wysyłkę.
- **Załącznik i tekst** - Messenger nie wysyła pliku i tekstu w jednej wiadomości, więc klient dostanie dwie: najpierw plik, potem tekst.
- **24 godziny** - Messenger pozwala odpowiadać swobodnie przez 24 godziny od ostatniej wiadomości klienta. Później odrzuci zwykłą odpowiedź i zobaczysz błąd. Po tym czasie można pisać tylko wiadomościami ze specjalnym oznaczeniem Meta (na przykład odpowiedzią konsultanta do 7 dni) - takich wiadomości jeszcze nie wysyłamy, więc napiszesz dopiero, gdy klient odezwie się pierwszy.

## Wymaga ponownego połączenia

Ten stan pojawia się, gdy Facebook przestał akceptować nasz dostęp do strony - na przykład po zmianie hasła, utracie uprawnień do strony albo odłączeniu aplikacji w ustawieniach Facebooka. Do czasu ponownego połączenia nie wyślesz odpowiedzi z tej strony.

1. Przejdź przez **Podłączenie konta** jeszcze raz i wybierz w oknie Facebooka **tę samą** stronę.
2. 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 strony.
- Nie zaczyna rozmów z klientami - odpowiadasz w rozmowach otwartych przez klienta.
- Nie wysyła wiadomości ze specjalnym oznaczeniem Meta, więc nie napisze do klienta po upływie 24 godzin.
- Nie obsługuje komentarzy pod postami ani wiadomości z Instagrama.

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

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

- `POST /integrations/messaging/messenger` - utworzenie integracji z wyniku okna Facebooka: `code` (jednorazowy kod autoryzacji) i `redirectUri` (adres strony, która otworzyła okno - musi być identyczny). Ponowne podłączenie tej samej strony odświeża istniejącą integrację.
- `GET /integrations/messaging/{integrationId}` - integracja: `accountName` (nazwa strony), `externalId` (identyfikator strony), `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/messenger`, 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.