Facebook Messenger Integration

Connect your Facebook Page to your AI agent

Facebook Messenger Integration#

Connect your Facebook Page to AlonChat to automatically respond to messages 24/7. Your AI agent will handle customer inquiries, collect leads, and seamlessly hand off to human agents when needed.

Prerequisites#

Before you begin:

  • Facebook Page (not personal profile)
  • Page admin access
  • Trained AlonChat agent
  • Facebook Business Account (recommended)

Note: Personal profiles cannot be connected - only Facebook Pages.

Step-by-Step Setup#

Step 1: Navigate to Deploy#

  1. Log in to AlonChat
  2. Select your agent
  3. Go to Deploy > Facebook Messenger
  4. Click Connect Facebook Page

Step 2: Log in to Facebook#

You'll see an OAuth popup to authorize the connection.

Required permissions:

  • pages_messaging - Send and receive messages
  • pages_read_engagement - Read comments and interactions
  • pages_manage_metadata - Update page settings

Click Continue to grant permissions.

Step 3: Select Facebook Page#

Choose which Facebook Page to connect:

  • If you manage multiple pages, select the one you want
  • Can connect different pages to different agents
  • If a page is already connected to another agent, you'll see a conflict dialog with a transfer option
  • Click "Add More" to connect additional pages

Click Connect Page.

Step 4: Configure Settings#

On the Facebook deploy page, configure:

  • Greeting Text: First message visitors see
  • Get Started Button: Custom welcome message/payload
  • Ice Breakers: Conversation starters
  • Quick Replies: Up to 13 quick reply buttons
  • Persistent Menu: Custom menu items (postback or web URL links)
  • Auto-Suggest Quick Replies: AI-generated contextual reply suggestions
  • Custom AI Prompt: Override or append to default prompt for Messenger
  • Learned Style: Use communication patterns from training
  • Auto-Reply Toggle: Enable/disable per connected page

Step 5: Test the Integration#

  1. Send a message to your Facebook Page from a test account
  2. Verify agent responds automatically
  3. Test handoff phrase: "I want to speak to a human"
  4. Check that conversation appears in AlonChat dashboard

How It Works#

Message Flow#

Code
User sends message to Facebook Page
          ↓
Facebook sends message to AlonChat via webhook
          ↓
AlonChat agent processes message (RAG retrieval)
          ↓
Agent generates response using AI model
          ↓
AlonChat sends response back to Facebook
          ↓
User receives response in Messenger

Average response time: 2-5 seconds

Conversation Syncing#

AlonChat syncs all Facebook Messenger conversations:

  • ✅ Real-time message sync (both directions)
  • ✅ Conversation history preserved
  • ✅ User profile information (name, profile picture)
  • ✅ Message read receipts
  • ✅ Typing indicators

View conversations: Go to Conversations tab in AlonChat dashboard to see all Facebook chats.

Features#

Auto-Response#

Agent automatically responds to:

  • Direct messages to your page
  • First-time messages
  • Follow-up questions
  • Messages during off-hours

Does NOT auto-respond to:

  • Messages you already replied to (unless new question asked)
  • Spam or abusive messages
  • Messages from blocked users

Handoff to Human Agents#

When a user requests human assistance:

  1. Trigger phrase detected (e.g., "speak to human")
  2. Agent responds: "Let me connect you with our team. They'll be with you shortly."
  3. Notification sent to your team (email, Slack, etc.)
  4. Auto-reply paused for that conversation
  5. Human takes over in AlonChat dashboard or Facebook Page Inbox

Resume AI:

  • Click "Resume AI Agent" in conversation view
  • Agent will continue responding automatically

Lead Collection#

Agent can collect lead information during conversations:

Example conversation:

Code
User: Do you offer custom t-shirt printing?
Agent: Yes! We offer custom printing with full-color designs.
      Would you like to receive our pricing guide?

User: Yes please

Agent: Great! May I have your email address?

User: john@example.com

Agent: Thank you! I'll send the pricing guide to john@example.com.
      What's your name?

User: John Doe

Agent: Thanks John! Would you like to provide your phone number
      so we can discuss your project?

User: +639171234567

Agent: Perfect! We'll reach out to you shortly. 🎉

Lead captured:

  • Name: John Doe
  • Email: john@example.com
  • Phone: +639171234567
  • Source: Facebook Messenger
  • Timestamp: 2025-11-26 10:30 AM

Webhooks triggered:

  • leads.submit event fires automatically
  • Can integrate with CRM, Google Sheets, etc.

Message Formatting#

Agent supports rich message formatting:

Text formatting:

  • Bold, italic, strikethrough (Markdown syntax)
  • Emojis 😊 🎉 ❤️
  • Line breaks and paragraphs

Media:

  • Images (sent as attachments)
  • Files (PDFs, documents)
  • Links (auto-preview in Messenger)

Quick replies (coming soon):

  • Button-style quick responses
  • Multiple choice options
  • Guided conversations

Best Practices#

1. Set Clear Expectations#

Add to your agent's system prompt:

Code
You are an AI assistant for [Company Name].
Let users know you're an AI at the start of conversations:
"Hi! I'm [Company]'s AI assistant. How can I help you today?"

2. Configure Handoff Triggers#

Add these phrases to trigger human handoff:

  • "speak to a human"
  • "talk to a person"
  • "real person"
  • "customer service"
  • "manager"
  • "complaint"

3. Set Appropriate Response Time#

For customer support:

  • Use 2-5 second delay (natural conversation feel)
  • Show typing indicator
  • Don't respond too fast (feels robotic)

For sales/marketing:

  • Can use instant responses (0s delay)
  • Emphasize speed and availability

4. Use Business Hours Wisely#

24/7 business:

  • Set "Always Reply" mode
  • Let AI handle all initial inquiries
  • Have human review in morning

Office hours business:

  • Set "Only When Offline" mode
  • Business hours: 9am-5pm Mon-Fri
  • AI covers nights, weekends

5. Monitor Conversations#

Check AlonChat dashboard daily:

  • Review AI responses for accuracy
  • Look for patterns in unanswered questions
  • Add missing information to knowledge base
  • Manually respond to complex queries

6. Train Your Agent#

Add Facebook-specific knowledge:

  • Common questions asked via Messenger
  • Typical follow-up questions
  • Messenger-specific FAQs
  • Tone appropriate for social media

Troubleshooting#

Agent Not Responding#

Check these:

  1. Integration status:

    • Go to Settings → Integrations
    • Ensure Facebook is "Connected" (green)
    • If not, click "Reconnect"

  2. Agent is trained:

    • Go to Settings → Knowledge Base
    • Ensure agent has been trained recently
    • Re-train if you added new sources

  3. Response mode:

    • Check Settings → Integrations → Facebook
    • Ensure "Response Mode" is set correctly
    • If "Only When Offline", check business hours

  4. Facebook permissions:

    • Go to Facebook Page → Settings → Advanced Messaging
    • Ensure "Connected Apps" shows AlonChat
    • Re-authorize if missing

  5. Webhook health:

    • Settings → Integrations → Health Check
    • Should show "Webhook: Active ✅"
    • If not, click "Repair Webhook"

Delayed Responses#

Possible causes:

  1. AI model is slow:

    • Go to Settings → AI Settings
    • Switch to faster model (e.g., Grok 4.1 or Gemini Flash)

  2. Large knowledge base:

    • Retrieval may be slow with 100+ sources
    • Optimize by removing duplicate content

  3. High traffic:

    • During peak hours, responses may slow
    • Upgrade to higher-tier plan for better performance

Duplicate Responses#

Symptoms: Agent sends the same message twice

Causes:

  • Facebook sends webhook twice (rare bug)
  • Integration was connected multiple times

Fix:

  1. Disconnect Facebook integration
  2. Wait 5 minutes
  3. Reconnect Facebook page
  4. Test with fresh message

Agent Says "I don't know"#

Causes:

  • Knowledge base is missing relevant information
  • Question phrasing doesn't match sources

Fix:

  1. Add missing information to knowledge base:

    • Upload documents
    • Create Q&A pairs
    • Add text sources

  2. Re-train agent:

    • Settings → Knowledge Base → Train Agent

  3. Test with exact phrases used by customers

Handoff Not Working#

Symptoms: Handoff phrase doesn't trigger human takeover

Fix:

  1. Go to Settings → Integrations → Facebook
  2. Review "Handoff Triggers" list
  3. Add the exact phrase used by customer
  4. Case-insensitive, so "Human" = "human"

Default triggers:

  • speak to a human
  • talk to a person
  • real person
  • customer service
  • manager

Disconnecting Facebook Page#

To disconnect a Facebook Page:

  1. Go to Settings → Integrations
  2. Find Facebook Messenger integration
  3. Click ⋮ (three dots) → Disconnect
  4. Confirm disconnection

What happens:

  • ✅ Agent stops auto-responding
  • ✅ Webhook is removed from Facebook
  • ✅ Existing conversations are preserved
  • ✅ Can reconnect anytime

Note: To connect a different page, disconnect first, then connect the new page.

Limitations#

  • One page per agent: Each agent can only connect to one Facebook Page
  • One agent per page: Each Facebook Page can only connect to one agent
  • Message limits: Facebook has rate limits (600 messages/min per page)
  • No Instagram Story replies: Only DMs and comments are supported
  • No group chats: Agent only responds to 1-on-1 conversations

Privacy & Compliance#

Data Collection#

AlonChat collects:

  • Message content (encrypted at rest)
  • User profile information (name, profile picture)
  • Conversation timestamps
  • Message read status

AlonChat does NOT collect:

  • Facebook account passwords
  • Private messages to other pages
  • User's friend list
  • User's posts or photos

GDPR Compliance#

AlonChat is GDPR-compliant:

  • ✅ User data is encrypted
  • ✅ Data is stored in secure servers
  • ✅ Users can request data deletion
  • ✅ Data is not sold to third parties

Data Retention#

  • Active conversations: Retained indefinitely
  • Archived conversations: 90 days (configurable)
  • User deletion: All data deleted within 30 days

Next Steps#

Facebook Messenger Integration | AlonChat Docs