[Intum](https://intum.fr/aide.md) / [Helpdesk](https://intum.fr/aide/helpdesk.md)

# [Integracja z Meta - Facebook Messenger, Instagram i komentarze](https://intum.fr/aide/social-media-messenger-instagram.md) | [API](#api)

Po włączeniu integracji wiadomości od klientów wysłane przez Facebook Messenger i Instagram DM automatycznie trafiają do Helpdesku jako tickety. Odpowiedzi agentów wracają do klienta na Messengerze lub Instagramie. Komentarze pod postami na Facebooku też trafiają do Helpdesku.

## Co obsługuje integracja

- Wiadomości z **Facebook Messenger** - każda rozmowa to osobny ticket
- **Instagram DM** - wiadomości prywatne z konta Instagram Business podłączonego do strony FB
- **Komentarze pod postami** na stronie Facebook - jeden wątek komentarzy to jeden ticket
- Odpowiedzi agenta lecą z powrotem na Messenger, Instagram lub pod komentarz
- Załączniki (zdjęcia, pliki) w obie strony

## Wymagania

- Konto z aktywnym modułem Helpdesk
- Strona na Facebooku (Page), na której jesteś administratorem
- Konto Instagram Business podłączone do strony FB (opcjonalnie, dla Instagram DM)

## Krok 1: Włącz integrację

Przejdź do **AppStore** i znajdź aplikację **Integracja z Meta** (sekcja Helpdesk). Kliknij **Aktywuj**.

Nie musisz nic konfigurować po stronie Facebooka ani w żadnej konsoli developerskiej. Integracja działa od razu po aktywacji.

## Krok 2: Podłącz stronę Facebook i Instagram

W sekcji **Połącz Facebook / Instagram** wybierz desk Helpdesku, do którego mają trafiać tickety, i kliknij **Połącz z Facebook / Instagram**.

Zostaniesz przekierowany do Facebooka, gdzie:
1. Zalogujesz się na swoje konto Facebook
2. Wybierzesz strony FB do podłączenia
3. Nadasz uprawnienia aplikacji

Po powrocie zobaczysz listę stron do potwierdzenia. Przy każdej stronie widać czy ma powiązane konto Instagram - z linkiem do profilu. Zaznacz strony które chcesz podłączyć i kliknij **Podłącz wybrane**.

## Krok 3: Zarządzaj podłączonymi stronami

Przy każdej podłączonej stronie możesz:
- Zmienić desk osobno dla Facebooka (Messenger + komentarze) i osobno dla Instagrama
- Włączyć lub wyłączyć odbiór wiadomości z Facebooka albo Instagrama niezależnie
- Odłączyć stronę przyciskiem **Odłącz**

Możesz podłączyć wiele stron FB do różnych desków.

## Jak to działa

**Odbiór wiadomości:**
- Klient pisze na Messengerze lub wysyła DM na Instagramie
- Wiadomość automatycznie trafia do Helpdesku jako nowy ticket (lub komentarz do istniejącego, jeśli rozmowa trwa)
- Ticket zawiera imię klienta i treść wiadomości
- Kolejne wiadomości od tego samego nadawcy trafiają do tego samego ticketu (dopóki jest otwarty)

**Odpowiedź z Helpdesku:**
- Agent odpowiada normalnie - dodaje komentarz do ticketu
- Odpowiedź automatycznie trafia do klienta na Messengerze lub Instagramie
- Klient widzi odpowiedź w swojej rozmowie

**Komentarze pod postami FB:**
- Komentarze pod postami na stronie FB trafiają do Helpdesku
- Agent może odpowiedzieć z Helpdesku - odpowiedź pojawi się jako komentarz pod postem

Komentarze wewnętrzne (notatki) nie są wysyłane do klienta.

## Odinstalowanie

Kliknij **Usuń integrację** na stronie aplikacji. Webhooki zostaną wyłączone, a odpowiedzi agentów przestaną trafiać do Facebooka. Istniejące tickety pozostają w Helpdesku.

## FAQ

**Czy mogę podłączyć kilka stron FB do różnych desków?**
Tak. Każda strona może być mapowana na inny desk.

**Czy Facebook i Instagram z tej samej strony mogą trafiać na różne deski?**
Tak. Przy każdej stronie możesz osobno wybrać desk dla Facebooka i desk dla Instagrama.

**Czy muszę zakładać własną aplikację Meta?**
Nie. Integracja działa na globalnej aplikacji Intum.

**Co jeśli chcę zmienić desk dla strony?**
Użyj dropdownu przy podłączonej stronie - możesz zmienić desk w dowolnym momencie.

**Czy obsługiwane są grupy na Facebooku?**
Nie, tylko strony (Pages).

**Dlaczego nie widzę swojej strony po powrocie z Facebooka?**
Facebook pokazuje tylko strony, na których masz rolę administratora. Jeśli jesteś tylko edytorem lub moderatorem strony, nie pojawi się na liście.

**Co się stanie gdy zmienię hasło do Facebooka?**
Integracja działa na tokenach strony, nie na haśle. Tokeny nie wygasają po zmianie hasła.

---

## 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**

## Architektura

Integracja działa jako plugin - connector `social_media/meta` + Noe App.

- Connector: `Connect::Connector` kind=`social_media/meta`
- UI: `app/src/noe/appstore/meta_social_integration.svelte`
- Backend: `app/src/connect/connector/social_media/meta.rb`
- Dokumentacja: `docs/llm/apps/meta_integration.md`

## Dane w connectorze

```
connector.config["pages"][page_id] = {
  page_name, page_access_token, app_secret, verify_token, ig_account_id
}  # system, read-only

connector.fields["pages"][page_id] = {
  desk_id, category_id, active, instagram_active
}  # user-editable
```

## Routing wiadomości

- `Connect::DataObject` object_name=`fb_mid` - dedup Messenger (object_id = mid)
- `Connect::DataObject` object_name=`fb_comment_id` - dedup komentarzy (object_id = comment_id)
- `Connect::DataObject` object_name=`fb_thread` - routing reply komentarza do ticketa (object_id = top_comment_id)
- `Connect::DataObject` object_name=`fb_sender` - routing DM nadawcy do otwartego ticketa (object_id = psid)
- `ticket.config["meta"]` - outgoing routing (sender_id, page_id, kind, top_comment_id)

## Webhook endpoints

```
POST /connect/connector/{code}/webhook_facebook   # FB Messenger + komentarze
POST /connect/connector/{code}/webhook_instagram   # Instagram DM
GET  /connect/connector/{code}/webhook_facebook    # verify (hub.verify_token)
GET  /connect/connector/{code}/webhook_instagram   # verify
```

Verify: `connector.config["pages"][page_id]["verify_token"]`
HMAC: X-Hub-Signature-256 z app_secret per strona.

## OAuth

```
GET /connect/connector/{code}/oauth_start?desk_id=X
GET /connect/connector/{code}/oauth_callback
```

State w `connector.config["oauth_states"]` z TTL 10 min.

## Outgoing (agent odpowiada)

`Account::Webhook` target_kind=`connector`, source_type=`Helpdesk::Comment`, kind=`create`
-> `dispatch_webhook_event` -> `MessengerSender` lub `CommentReplier`

## Credentials

Globalne: `Rails.application.credentials.dig(:meta, :app_id / :app_secret)`
Fallback per-connector: `fields["app_id"]` + `secret_token`