Skip to content
Sugester V2 EN

Facebook Messenger integration with Helpdesk

Updated at: • 4 min read

Go to section

  1. How Facebook Messenger integration → Helpdesk works
  2. Flow
  3. Configuration — step by step
  4. 1. Meta App
  5. 2. Page Access Token
  6. 3. Webhook Subscription
  7. 4. Configuration in Intum
  8. 5. Test
  9. 6. Go Live (important for production!)
  10. Connecting multiple pages
  11. Attachments
  12. Security
  13. Technical details
  14. Files in code

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 → 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

Was this entry helpful?

Share

Comments