[Sugester V2 EN](https://sugester.intum.com/kb/sugester-v2-en.md)

# [Facebook Messenger integration with Helpdesk](https://sugester.intum.com/kb/sugester-v2-en/facebook-messenger-integration-with-helpdesk.md)

## How Facebook Messenger integration → Helpdesk works

Messages sent to the Facebook page's Messenger automatically arrive as tickets in Helpdesk. Agent responses from tickets return to Messenger — along with attachments (images, files).

### Flow

1. The client writes on the FB Messenger (text, images, files)
2. Meta sends a webhook to Intum (verified by X-Hub-Signature-256)
3. Background processing (SolidQueue) — the system creates a ticket or adds a comment to an existing one (grouping by sender)
4. The agent responds with a comment in the ticket → the response (text + attachments) goes to Messenger

### Configuration — step by step

#### 1. Meta App

We use a shared app **Sugester Helpdesk** (App ID: `3379478975539191`).
New FB pages subscribe to the same app — there is no need to create a new one.

#### 2. Page Access Token

1. [Meta for Developers](https://developers.facebook.com/) → Your App → **Messenger → Settings → Access Tokens**
2. Click **Add or Remove Pages** → select the page → generate token
3. Copy the token — it will be needed in step 4

> **Note:** PAGE tokens generated from a long-lived user token are **permanent** (do not expire). This can be verified through the `debug_token` endpoint — it should show `expires_at: 0` (NEVER).

#### 3. Webhook Subscription

1. Meta App → **Messenger → Settings → Webhooks**
2. **Callback URL:** `https://SERWER.intum.com/social_media/webhooks/facebook`
3. **Verify Token:** any string (the same you will enter in Intum, e.g., `sm_verify_sugester_2026`)
4. **Subscribe fields:** `messages` (mandatory)
5. Click **Verify and Save**

> Each FB page must be separately subscribed to the webhook.
> In the "Webhooks" section for the given page, click **Subscribe** next to the `messages` field.

#### 4. Configuration in Intum

1. **Helpdesk → Desks** → select desk → **Edit** → **Messenger** tab
2. Fill in:
   - **Page ID** — from the page settings on Facebook (About → Page transparency)
   - **Page Name** — name of the page (for display)
   - **Page Access Token** — from step 2
   - **App Secret** — from Meta App → Settings → Basic
   - **Verify Token** — the same as in step 3
   - **Default category** — optional, a category with an assigned owner (tickets will get auto-assignment)
3. Check **Messenger active**
4. Save

> **Suggestion:** Create a separate desk "Social Media" to handle Messenger, WhatsApp, Viber, etc. This way, tickets from social media are separated from emails/phones, and a dedicated owner sees them in their desk. Attach a category with the responsible team/person — tickets will be automatically assigned.

#### 5. Test

Send a message on the page's Messenger. It should appear as a ticket in Helpdesk.
Reply with a comment from the ticket — it should return to Messenger.

#### 6. Go Live (important for production!)

Without this step, **only admins and testers** of the Meta app can send messages:

1. Meta App → **App Review → Permissions and Features**
2. Request **pages_messaging**
3. Requires:
   - Privacy Policy URL
   - Description of how we use Messenger
   - Demonstration screencast
4. After approval: **App Dashboard → Go Live**

### Connecting multiple pages

Each FB page can be connected to **a different Helpdesk desk**:

| FB Page    | Helpdesk Desk        | Page ID                |
|------------|----------------------|------------------------|
| Sugester   | Social Media         | `107381679302250`      |
| Fakturownia| Fakturownia Support   | *(to be completed)*    |

The webhook URL is shared — the system routes by `page_id` to the appropriate desk.

### Attachments

- **FB → Intum:** Images, files, audio, video from Messenger arrive in the ticket as attachments (markdown)
- **Intum → FB:** Attachments added to the comment (images as `image`, others as `file`) automatically go to Messenger via the Send API. In production, it uses CloudFront signed URL.

### Security

- **X-Hub-Signature-256:** Each webhook from Meta is verified with an HMAC-SHA256 signature (from App Secret). Forged webhooks are rejected.
- **Background processing:** The webhook immediately returns 200 OK, and processing (ticket creation) happens asynchronously in SolidQueue — this way, Meta does not get a timeout.

### Technical details

- **Grouping:** Messages from the same sender go into one ticket (as comments) until the ticket is closed
- **Sender profile:** Retrieved from Graph API (first name, last name, photo) — requires App Review for `pages_messaging` for non-admins
- **Duplicates:** The system checks `message_id` (mid) to avoid processing the same message twice
- **Source:** A ticket from Messenger has `config.source = "facebook_messenger"` and sender data in `config`
- **Default category:** Connection stores `category_id` in `config` JSONB — the ticket gets a category, and the callback `set_responsible_from_category` automatically assigns the owner

### Files in code

```
app/models/social_media/connection.rb              — connection model (FB page → desk)
app/controllers/social_media/webhooks_controller.rb — webhook endpoint (signature verification + async)
app/jobs/social_media/process_webhook_job.rb        — SolidQueue job for processing webhooks
app/src/social_media/facebook_parser.rb             — Meta payload parser
app/src/social_media/ticket_creator.rb              — ticket/comment creation
app/src/social_media/messenger_sender.rb            — sending responses and attachments to Messenger
app/views/helpdesk/desks/_form.html.erb             — Messenger tab in the desk form
app/views/helpdesk/desks/show.html.erb              — Messenger tab in the desk preview
```