How to connect Facebook Messenger to an AI Agent
Connect your Flametree AI agent to Facebook Messenger to automatically process and respond to messages sent to your Facebook Page. This integration uses the official Facebook Graph API and supports multi-account, round-robin outbound messaging.
Prerequisites
- Facebook Developer Account — Register at developers.facebook.com
- Facebook Page — The agent will respond as this page
- Facebook App — Created in the Facebook Developer Console
- Admin access to your Flametree account
Setting Up Facebook Messenger Integration
Step 1: Create Facebook App and Page
-
Create a Facebook Page
- Go to facebook.com/pages/create and follow the prompts
-
Create a Facebook App
- Go to developers.facebook.com/apps
- Click Create App
- Select Business as the app type
- Enter app name, contact email, and select your business account
-
Add Messenger Product
- In your app dashboard, click Add Product
- Find Messenger and click Set Up
Step 2: Generate Access Tokens and IDs
-
Link Facebook Page to App
- In Messenger > Settings, add your Facebook Page
-
Generate Page Access Token
- In Messenger > Settings, under Access Tokens, select your page and click Generate Token
- Save this token — you’ll need it for Flametree
-
Collect Required Parameters
- Page ID: In Messenger > Settings or from your page URL
- App ID: In Settings > Basic
- App Secret: In Settings > Basic
- Verify Token: Arbitrary string you choose (used for webhook verification)
Step 3: Configure Webhook
-
Set up Webhook in Facebook App
- In Messenger > Settings, click Add Callback URL
- Enter the callback URL provided by Flametree (see below)
- Enter your Verify Token (must match the value you provide in Flametree)
- Subscribe to the following events:
messages,messaging_postbacks
-
Callback URL
- The callback URL will be provided in the Flametree channel setup screen after you create the integration
Step 4: Collect Integration Parameters
Save these values from the Facebook Developer Console:
| Parameter | Location in Meta Console |
|---|---|
| App ID | Settings > Basic |
| App Secret | Settings > Basic |
| Page ID | Messenger > API Settings |
| Access Token | Messenger > API Settings |
Configuring Flametree Integration
Step 1: Create Facebook Messenger Integration
-
Navigate to Settings
- Go to Settings > Channels
- Open Facebook Messenger
- Select Add +
-
Fill Configuration
| Field | Description | Required | Value Source |
|---|---|---|---|
| Name | Custom integration name | ✅ Yes | Support Email Connector |
| Description | Integration purpose | ✅ Yes | Customer support email integration |
| App ID | Default Meta app to subscribe webhook | ✅ Yes | Meta Console |
| App secret | Stored near the App ID in Meta console | ✅ Yes | Meta Console |
| Page ID | Facebook page ID * | ✅ Yes | Meta Console |
| Access token | Facebook page API token * | ✅ Yes | Meta Console |
* Field can accept multiple values
If a field supports multiple values, separate them with a comma (,).
Example: 1234567890, 9876543210
When you connect multiple Facebook accounts to the same channel, Flametree sends outbound messages through these accounts one by one in a fixed repeating sequence (round-robin). You can add as many Facebook accounts as needed, there is no limit.
After a recipient receives their first message, Flametree links that recipient to the specific Facebook account that sent it. From that moment on, Flametree always sends messages to this recipient from the same Facebook account. This keeps the sender identity consistent and reduces the risk of messages being blocked.
- Save Integration
- Click Save to create the integration
Step 2: Connect to AI Agent
-
Open Agent Configuration
- Navigate to your target AI agent's settings
- Go to Communication channels section
-
Assign Channel
- Select your Facebook Messenger integration from the list
- Save the agent configuration
-
Restart Agent
- Restart the agent for changes to take effect
- This step is mandatory for the integration to work
❗️ Important: Always restart both the agent and channel after making changes.
Configuration Options
Environment Variables
Configure additional features through Set Environment Variables:
| Variable | Description | Default |
|---|---|---|
FB_REGISTRATION_DELAY | Delay (seconds) between webhook registration attempts | 5.0 |
FB_REGISTRATION_COUNT | Number of webhook registration attempts | 20 |
Testing Your Integration
Quick Test Steps
-
Send a Message
- Go to your Facebook Page as a user (not as an admin)
- Send a message to the page
-
Verify Response
- The AI agent should respond automatically
-
Test Carousel and Attachments
- Send a message with a list or media to test advanced features
Common Issues & Solutions
Webhook verification fails
Possible causes:
- Incorrect verify token
- Callback URL not reachable
- Facebook app not in Live mode
Solutions:
- Match verify tokens: Ensure the verify token in Facebook and Flametree match
- Check callback URL: Ensure Flametree server is accessible from Facebook
- Switch app to Live mode: In App Settings > Basic, set App Mode to Live
Messages not delivered
Possible causes:
- Agent not restarted
- Invalid access token
- Facebook Page not linked to app
Solutions:
- Restart agent: Restart your Flametree agent after integration setup
- Verify token: Check if access token is still valid in Facebook console
- Check page linkage: Ensure your Facebook Page is linked to the app in Messenger > Settings
Only admins can message the bot
Possible causes:
- App is in Development mode
Solution:
- Switch app to Live mode in App Settings > Basic
FAQ
Can I use the same Facebook Page for multiple agents?
It depends on the channel mode:
- ✅ Yes — If you're using the channel in outbound mode only
- ❌ No — If any subscribed agent has already activated inbound mode
Why this limitation exists:
- Multiple agents listening for inbound messages on the same page would cause conflicts
- Messages might be processed by multiple agents simultaneously
- Response duplication and inconsistent behavior would occur
Best practice: Use dedicated Facebook Pages for each agent to ensure reliable message handling and avoid conflicts.
What message types are supported?
Flametree Facebook Messenger integration supports:
- ✅ Text messages
- ✅ Carousels (generic templates)
- ✅ Attachments (images, audio, documents)
- ✅ Quick replies and postbacks
Do I need to switch the app to Live mode?
Yes, to allow non-admin users to message your bot, you must switch your Facebook app to Live mode in the Facebook Developer Console.
Security Considerations
API Token Security
- Never share your access tokens publicly
- Rotate tokens regularly using Facebook console
- Use environment variables in production deployments
- Monitor API usage for suspicious activity
Page and App Security
- Enable two-factor authentication on your Facebook account
- Limit admin access to essential personnel only
- Regular audit of app permissions and access tokens
- Monitor webhook endpoints for unauthorized access
Privacy Compliance
- GDPR compliance: Ensure message handling meets data protection requirements
- Data retention: Configure appropriate message retention policies
- User consent: Implement proper opt-in mechanisms for marketing messages
- Encryption: All messages are encrypted by Facebook in transit