[Intum](https://intum.pl/pomoc.md) / [Integracje](https://intum.pl/pomoc/integracje.md) # [Integracja z Meta (Facebook Messenger, Instagram, komentarze pod postami)](https://intum.pl/pomoc/integracje/integracja-z-meta-facebook-messenger-instagram-komentarze-pod-postami.md) | [API](#api) ## Co daje ta integracja Wiadomości z Facebook Messengera, Instagram DM oraz komentarze pod postami na stronie FB trafiają jako tickety do Twojego Helpdesku. Agent odpowiada w tickecie tak samo jak na każdym innym kanale, a odpowiedź wraca do klienta - na Messenger, Instagram lub pod komentarz na Facebooku. Każda strona FB jest podłączona do wybranego desku Helpdesku, dzięki czemu możesz rozdzielić obsługę sprzedaży, supportu i marketingu na różne zespoły. ## Co potrzebujesz - Konto Facebook z rolą administratora strony firmowej - Dla Instagrama: konto Instagram Business połączone ze stroną FB (osobiste i Creator nie zadziałają) - Co najmniej jeden desk w Helpdesku, do którego mają trafiać tickety ## Instalacja 1. Wejdź w **Aplikacje** w menu konta (`/account/apps`) 2. Znajdź kafelek **Integracja z Meta** i kliknij **Zainstaluj** 3. Otwórz zainstalowaną aplikację - dalsza konfiguracja toczy się w niej ## Konfiguracja krok po kroku ### 1. Utwórz konektor W oknie aplikacji kliknij **Konfiguruj integrację z Meta**. Pola App ID i App Secret zostaw puste - domyślnie używamy globalnych poświadczeń Intum. Własne wpisuj tylko jeśli korzystasz z dedykowanej aplikacji Meta. Po utworzeniu konektora system od razu włącza webhook zwrotny. To znaczy, że odpowiedzi agentów będą same lecieć do klienta - nic więcej nie musisz konfigurować po stronie Intum. ### 2. Webhooki w Meta App Dashboard W Meta App Dashboard otwórz swoją aplikację i przejdź do sekcji **Webhooks**. Dodaj dwie subskrypcje: Facebook Page: - Callback URL: skopiuj z aplikacji w Intum (przycisk **Kopiuj** obok URL-a) - Eventy: `messages` (wiadomości Messenger) i `feed` (komentarze pod postami) Instagram: - Callback URL: drugi URL z aplikacji w Intum - Event: `messages` Verify token generujemy automatycznie podczas podłączania strony przez OAuth - zobaczysz go w panelu Meta po pierwszym połączeniu. ### 3. Podłącz strony FB W sekcji **Połącz stronę FB z deskiem** wybierz desk Helpdesku i kliknij **Połącz stronę FB**. Wylądujesz na Facebooku: 1. Wybierz stronę firmową, którą chcesz podłączyć 2. Nadaj uprawnienia (czytanie wiadomości, odpowiadanie, zarządzanie komentarzami) 3. Po powrocie zobaczysz potwierdzenie i strona pojawi się na liście Powtórz dla każdej strony, którą chcesz podpiąć. Schemat jest prosty: jedna strona FB = jeden desk Helpdesku. ## Jak to działa w praktyce Klient pisze na Messengerze do Twojej strony FB. Po stronie Intum tworzy się nowy ticket w desku przypisanym do tej strony. Imię i nazwisko klienta bierzemy z profilu FB. Agent odpowiada w tickecie - normalnie, w polu komentarza. Treść od razu leci do klienta jako wiadomość Messenger. Tak samo z Instagramem. Komentarze pod postami FB działają trochę inaczej. Cały wątek komentarza (główny komentarz plus odpowiedzi) staje się jednym ticketem. Gdy agent odpowie, odpowiedź pojawia się jako reply pod tym komentarzem na FB. Załączniki (obrazki, pliki) z Messengera trafiają jako załączniki ticketu. Obrazy z komentarzy FB przekazujemy jako załączniki obrazu w odpowiedzi. ## Częste problemy **Nie widać przycisku Połącz stronę FB** - najpierw musisz utworzyć desk w Helpdesku. Wróć do ustawień Helpdesku i dodaj choć jeden. **Po OAuth nic się nie podłączyło** - sprawdź czy Twoje konto FB ma rolę administratora strony. Bez tego Facebook nie pozwoli wygenerować tokenów dostępu dla strony. **Wiadomości z Instagrama nie przychodzą** - konto Instagram musi być typu Business i połączone ze stroną FB. Konta osobiste i Creator nie wystawiają wiadomości w API Mety. **Komentarze pojawiają się jako tickety, a chcę tylko DM-y** - obie funkcje są włączone razem przy subskrypcji webhooka. Jeśli chcesz wyłączyć komentarze, w Meta App Dashboard usuń subskrypcję `feed` zostawiając samo `messages`. **Webhook nie weryfikuje się przy zapisywaniu w Meta** - Meta wywołuje GET na callback URL z parametrem `hub.verify_token`. Verify token jest generowany przy pierwszym OAuth, więc kolejność jest taka: najpierw zapisz subskrypcję z dowolnym tokenem (Meta zwróci błąd weryfikacji), potem zrób OAuth strony, potem wróć do Meta i wpisz token wygenerowany dla tej strony. ## Usuwanie integracji W aplikacji w Intum, w widoku szczegółów konektora, kliknij **Usuń integrację**. To zrobi: - Skasuje webhook zwrotny (agenci przestaną wysyłać odpowiedzi na Messengera/Instagrama/FB) - Usunie konektor wraz z konfiguracją podłączonych stron - Zostawi nietknięte tickety w Helpdesku - tylko przestają być powiązane z Metą Uwaga: subskrypcje webhooków w Meta App Dashboard nie kasują się automatycznie. Jeśli już nie planujesz używać integracji, usuń je ręcznie w panelu Meta, żeby nie próbowały wysyłać payloadów na martwy URL. --- ## API ### Ogólne API # Intum API Dokumentacja API platformy [Intum](https://intum.pl) - system operacyjny firmy. ## Host Host jest zawsze taki sam jak adres konta: `xxxx.intum.com` lub `xxx.intum.pl` (w zależności od ustawień konta) ## Autoryzacja Wszystkie requesty API wymagają `api_token`: - header: `Authorization: Bearer TOKEN` Token możesz wygenerować w **Ustawienia Konta** → **Tokeny API** ## Konektor `social_media/meta` Pola modelu `Connect::Connector`: - `kind`: `social_media/meta` - `code`: zwykle `meta_social` (per konto) - `secret_token`: App Secret aplikacji Meta - per-konektor fallback dla `Rails.application.credentials.meta.app_secret` - `fields.app_id`: App ID aplikacji Meta - fallback dla `Rails.application.credentials.meta.app_id` - `config.pages[]`: konfiguracja strony FB - `page_name`, `page_access_token`, `app_secret`, `verify_token`, `desk_id`, `category_id`, `instagram_active`, `ig_account_id` - `config.oauth_states`: tymczasowe state-y OAuth, czyszczone po callbacku ## Endpointy publiczne (allow_public) | Metoda | URL | Opis | |--------|-----|------| | GET | `/connect/connector/{code}/webhook_facebook` | Weryfikacja Meta (hub.challenge) | | POST | `/connect/connector/{code}/webhook_facebook` | Wiadomości Messenger + komentarze feed | | GET | `/connect/connector/{code}/webhook_instagram` | Weryfikacja IG | | POST | `/connect/connector/{code}/webhook_instagram` | Wiadomości IG DM | | GET | `/connect/connector/{code}/oauth_start?desk_id=X` | Start OAuth (wymaga sesji agenta) | | GET | `/connect/connector/{code}/oauth_callback` | Powrót z OAuth | ## Metody `connector_method` - `check` - sprawdza poświadczenia przez Graph API (`/v21.0/{app_id}?fields=id,name`) - `pages` - zwraca listę podłączonych stron z config - `install_outgoing_webhook` - idempotentnie zakłada `Account::Webhook` (`target_kind=connector`, `target_code=`, `source_type=Helpdesk::Comment`, `kind=create`) - `uninstall_outgoing_webhook` - usuwa Account::Webhook tego konektora Wywołanie: ``` POST /connect/connectors/{id}/method/install_outgoing_webhook Authorization: Bearer TOKEN ``` ## Routing wiadomości Stan trzymamy w `Connect::DataObject` (`connector_id` + `object_name` + `object_id` UNIQUE): - `fb_mid` - dedup wiadomości Messenger (object_id = mid) - `fb_comment_id` - dedup komentarzy FB (object_id = comment_id, data: ticket_id) - `fb_ticket` - routing ticket → sender/page (object_id = ticket_id, data: `sender_id` / `top_comment_id`, `page_id`, `kind` = `messenger`|`instagram`|`comment`) ## Outgoing dispatch `Account::Webhook#deliver!` z `target_kind=connector` wywołuje `connector.dispatch_webhook_event(source_type:, kind:, record:)`. Dla `Helpdesk::Comment#create`: 1. Skip jeśli `comment.internal?` lub `comment.created_by_id.blank?` (komentarz klienta) lub `comment.fields["ai_comment"]` 2. Szuka routingu w `DataObject(object_name: "fb_ticket", object_id: ticket_id)` 3. Wysyła przez Messenger Send API (`POST /me/messages`) albo Graph Comments API (`POST /{comment_id}/comments`) w zależności od `kind` ## Weryfikacja podpisu Przychodzące webhooki Meta są podpisane nagłówkiem `X-Hub-Signature-256` (HMAC-SHA256 z App Secret). Bez nagłówka payload jest tolerowany (dev), z nieprawidłowym - odrzucany cicho (HTTP 200 ok, ale bez przetwarzania, żeby Meta nie wyłączała subskrypcji). Per-page secret w `config.pages[id].app_secret`, fallback na globalny `secret_token` konektora. ## OAuth scope ``` pages_messaging pages_manage_metadata pages_read_engagement pages_read_user_content pages_manage_engagement pages_show_list instagram_basic instagram_manage_messages ``` ## Instalator (Noe App) `Noe::Appstore::NoeAppstore::INTEGRATIONS[:meta_social]`: - `url_code`: `meta-social-integration` - `svelte`: `meta_social_integration.svelte` - `show_in_module`: `helpdesk/settings` - `helplink`: `account_apps_meta_social` Instalacja: `Noe::Appstore::NoeAppstore.install_app(:meta_social)` (lub przez UI `/account/apps`).