Facebook Messenger Integration

​

What is Messenger Integration?

Messenger Integration lets your IllumiChat assistants respond to Facebook Messenger conversations automatically. When someone messages your Facebook Page, your assistant reads the message, generates a helpful response, and sends it back — all via Messenger. Perfect for:

• Customer support: Let customers message your Facebook Page for instant AI-powered help
• Lead engagement: Capture and respond to inbound leads from Facebook 24/7
• After-hours coverage: Provide instant responses even when your team is offline
• Human handoff: Seamlessly transfer conversations to a human agent when needed

​

Getting Started

​

Prerequisites

Before setting up Messenger, you’ll need:

1. An IllumiChat workspace with Admin access
2. A Facebook Page that you manage (you must be a Page admin)
3. A Meta App with Business Verification completed (for production use)
4. The Meta App must have the Messenger product added

​

1. Connect Your Facebook Page

1. Go to your assistant’s Settings
2. Select Channels from the sidebar
3. Click the Messenger card
4. Click Connect with Facebook
5. Log in to Facebook and authorize the required permissions
6. Select the Facebook Page you want to connect
7. Click Connect

IllumiChat will:

• Verify your Page Access Token and messaging permissions
• Subscribe the Page to Messenger webhook events (messages, postbacks, delivery receipts, read receipts)
• Encrypt and store your Page Access Token securely

​

2. Configure Settings

After connecting, configure your Messenger settings:

​

3. Configure Messenger Profile

Customize how your Facebook Page appears in Messenger:

​

4. Test It Out

Send a message to your connected Facebook Page via Messenger. Within a few seconds, you should receive an AI-generated response.

​

How It Works

When someone sends a Messenger message to your Facebook Page:

1. Meta receives the message and forwards it to IllumiChat via webhook
2. IllumiChat validates the request using the X-Hub-Signature-256 header
3. A conversation session is created (or resumed) for that user using their Page-Scoped User ID (PSID)
4. A typing indicator is shown to the user while your assistant generates a response
5. Your assistant generates a response using its system prompt with Messenger-specific guidelines
6. The response is formatted — markdown is stripped and the message is kept under 2000 characters
7. The response is sent back via the Meta Send API
8. The full conversation is saved to your chat history for review

Your assistant automatically adapts to Messenger by keeping responses conversational, using short paragraphs (chat bubbles), and including emojis where appropriate.

​

Message Handling

Messenger has a 2000 character limit per message. If your assistant generates a longer response:

• Markdown formatting is automatically stripped (headers, bold, code blocks, links)
• The message is split at paragraph boundaries, then sentence boundaries, then word boundaries
• Each chunk is sent as a separate Messenger message to maintain readability
• Line breaks and emojis are preserved

​

Messaging Windows

Messenger enforces a 24-hour messaging window. Your assistant can only send automated responses within 24 hours of the user’s last message. After that window expires:

• AI responses: Cannot be sent until the user sends a new message
• Human Agent messages: Can be sent for up to 7 days using the Human Agent message tag (requires Meta approval)

​

Get Started Button

When configured, a “Get Started” button appears at the bottom of new Messenger conversations. When a user taps it:

1. A postback event is sent to IllumiChat
2. A new conversation session is created
3. Your assistant generates and sends a welcome response

This is a great way to onboard new users and set the tone for the conversation.

​

Attachments

Currently, IllumiChat processes text messages only. If a user sends an image, video, or other attachment, the assistant responds with a message explaining that it can only handle text at this time.

​

Human Takeover

Sometimes a conversation needs a human touch. Messenger Integration includes a full human takeover system that lets your team step in, respond directly, and hand back to AI when ready.

​

Activating Takeover

1. Go to your assistant’s Channels > Messenger page
2. Open the Conversations list
3. Find the conversation you want to take over
4. Click Take Over
5. Optionally set an auto-resume timer (5 minutes to 7 days)

When takeover is active:

• AI stops responding to that conversation
• The conversation shows a Human badge
• Admins can send messages directly to the user

​

Sending Messages as a Human

While in takeover mode, use the send message interface to type and send messages directly to the Messenger user. Messages are sent through the Meta Send API just like AI responses. If the 24-hour standard messaging window has expired, messages are automatically sent using the HUMAN_AGENT message tag, which extends the window to 7 days.

​

Resuming AI

To hand the conversation back to AI:

1. Click Resume AI on the conversation
2. AI immediately starts responding to new messages from that user

​

Auto-Resume

When activating takeover, you can set an auto-resume timer. After the specified duration, AI automatically resumes for that conversation. This prevents conversations from staying in human mode indefinitely if an agent forgets to hand back. Timer options range from 5 minutes to 7 days (10,080 minutes).

​

Messenger Analytics

Track how your Messenger integration is performing from the Analytics dashboard.

​

Usage Metrics

• Total Messages: Combined inbound and outbound message counts
• Inbound Messages: Messages received from users
• Outbound Messages: Messages sent by your assistant or human agents
• Delivered Messages: Messages confirmed as delivered by Meta
• Read Messages: Messages confirmed as read by the recipient
• Delivery Rate: Percentage of outbound messages successfully delivered
• Read Rate: Percentage of outbound messages read by recipients

​

Conversation Metrics

• Total Conversations: All Messenger conversations (across all time)
• Active Conversations: Conversations with messages in the selected period
• Human Takeover Count: Conversations currently in human takeover mode

​

Daily Breakdown

View message volume by day to identify trends and peak usage periods. The chart shows inbound vs outbound messages over time. Access analytics from your assistant’s Channels > Messenger detail page. Filter by time period: 7 days, 30 days, or 90 days.

​

Conversations

Browse Messenger conversations from the Conversations section on the Messenger channel page. Each conversation shows:

• User name and profile picture (fetched from Facebook)
• AI or Human badge (whether AI is actively responding)
• Message count and last activity time
• Messaging window expiry (whether you can still send messages)
• Auto-resume time (if takeover is active with a timer)

​

Admin Configuration

All Messenger management requires Admin role in the workspace. Admins can:

• Connect and disconnect Facebook Pages
• Enable/disable the Messenger channel
• Update settings (max message length, contact matching, greeting text)
• View analytics and conversation history
• Activate and manage human takeover
• Send messages as a human agent

​

Best Practices

​

Troubleshooting

​

No Facebook Pages found during setup

• Ensure the Facebook user authorizing the connection is an admin of the Page
• The Page must exist and be published (unpublished Pages may not appear)
• If re-authorizing, make sure to grant all requested permissions (especially pages_messaging and pages_manage_metadata)
• The setup screen will display a diagnostic hint explaining why no Pages were found

​

Not receiving messages

• Verify the Messenger channel is enabled in your configuration
• Check that the connection status shows Active on the config page
• Ensure your Meta App has the Messenger product configured
• In development mode, the sender must have a role on the Meta App

​

Token expired or revoked

Page Access Tokens can expire if the underlying user token is revoked or the app permissions are removed. If you see a connection status of “Expired” or “Revoked”:

1. Go to your assistant’s Channels > Messenger page
2. Click Reconnect to re-authorize with Facebook
3. Your existing configuration, settings, and conversation history are preserved

​

Messages not delivering

• Check the Analytics dashboard for failed message counts
• Ensure the conversation is within the 24-hour messaging window (or use human takeover with the HUMAN_AGENT tag)
• Verify your Meta App has completed App Review for production messaging
• Check the Meta Platform Status for outages

​

Get Started button not appearing

• The Get Started button may take a few minutes to propagate after configuration
• Verify you’ve set a Get Started payload in the Messenger settings
• The button only appears in new conversations — existing threads won’t show it
• Clear your Messenger conversation history to test with a fresh thread

​

Meta App Review issues

To send messages to users outside your development team, your Meta App needs approval:

• Submit for review with the pages_messaging permission
• Provide a clear description of your bot’s purpose
• Include a screencast showing how the bot responds to messages
• Ensure your bot complies with Meta’s Platform Policies