Facebook Messenger Integration#

Connect your Facebook Page to send and receive messages via Facebook Messenger.

Overview#

Features#

• Send and receive text messages
• Rich media (images, videos, files)
• Quick replies and buttons
• Persistent menus
• Message templates
• Automatic token management

Prerequisites#

• Facebook Page (not personal profile)
• Facebook Business Manager account
• Page admin access

Setup Guide#

Step 1: Connect via OAuth#

1. In Outeract console, go to Connections → Add Connection
2. Select Facebook Messenger
3. Click Connect with Facebook
4. Log in to Facebook
5. Select your Facebook Page
6. Grant required permissions:
   • pages_messaging
   • pages_manage_metadata
   • pages_show_list
7. Connection is created automatically

Step 2: Webhook Configuration#

Facebook Messenger uses a shared webhook architecture:

• One webhook URL handles all Messenger connections
• Routing is automatic based on Page ID
• Configure once in your Meta App settings

Step 3: Verify Connection#

mutation {
  testPlatformConnection(id: "pc_facebook_123") {
    success
    message
    health {
      status
    }
  }
}

Sending Messages#

Text Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_facebook_123"
    toExternalId: "1234567890123456"  # Page-scoped User ID
    message: "Thanks for contacting us!"
  ) {
    id
    status {
      success
    }
  }
}

Image Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_facebook_123"
    toExternalId: "1234567890123456"
    message: "Here's the product photo"
    fileIds: ["file_xyz789"]
  ) {
    id
  }
}

Supported Message Types#

External ID Format#

Facebook uses Page-scoped User IDs (PSID):

**Note**: PSIDs are unique per Page. The same user has different IDs across different Pages.

Messaging Window#

Facebook Messenger has messaging policies:

Standard Messaging#

• 24-hour window after user message
• Can send any message type

Message Tags#

Outside 24-hour window, use approved tags:

• CONFIRMED_EVENT_UPDATE
• POST_PURCHASE_UPDATE
• ACCOUNT_UPDATE
• HUMAN_AGENT (within 7 days)

Sponsored Messages#

For marketing outside the window (requires ad account).

Rich Message Types#

Quick Replies#

mutation {
  sendMessage(
    platformConnectionId: "pc_facebook_123"
    toExternalId: "1234567890123456"
    message: "How can I help you?"
    quickReplies: [
      { title: "Sales", payload: "SALES" },
      { title: "Support", payload: "SUPPORT" },
      { title: "Hours", payload: "HOURS" }
    ]
  ) {
    id
  }
}

Button Template#

mutation {
  sendTemplateMessage(
    platformConnectionId: "pc_facebook_123"
    toExternalId: "1234567890123456"
    template: {
      type: "button"
      text: "What would you like to do?"
      buttons: [
        { type: "postback", title: "View Order", payload: "VIEW_ORDER" },
        { type: "web_url", title: "Visit Website", url: "https://example.com" }
      ]
    }
  ) {
    id
  }
}

Webhook Events#

Inbound Message#

{
  "event_id": "evt_abc123",
  "event_type": "message.inbound",
  "payload": {
    "message": {
      "text": "Hello!",
      "role": "user"
    },
    "platform": "facebook",
    "external_message_id": "mid.xxx"
  },
  "edges": {
    "sent_by": {
      "external_id": "1234567890123456"
    }
  }
}

Postback Event#

{
  "event_id": "evt_xyz789",
  "event_type": "postback",
  "payload": {
    "payload": "VIEW_ORDER",
    "title": "View Order"
  }
}

Token Management#

Facebook uses Page Access Tokens:

• Duration: 60 days (long-lived)
• Auto-refresh: Outeract refreshes before expiry
• Reconnect: If issues occur, reconnect via OAuth

Rate Limits#

Troubleshooting#

“Permission denied”#

• Verify you’re a Page admin
• Check required permissions are granted
• Ensure Page is published (not unpublished)

“User not found”#

• Verify PSID is correct for your Page
• Check user hasn’t blocked your Page
• Ensure user has messaged your Page first

“Cannot send message”#

• Check 24-hour messaging window
• Use message tags if outside window
• Verify Page isn’t restricted

“Token expired”#

• Tokens auto-refresh every 60 days
• Reconnect via OAuth if persistent
• Check Page permissions in Business Manager

Facebook Platform Policies#

Permitted Use#

• Customer support
• Order notifications
• Appointment reminders
• Informational bots

Requirements#

• Respond to messages promptly
• Provide human escalation option
• Clear bot disclosure
• Respect user opt-outs

See Facebook Platform Policy for full guidelines.

Security#

Facebook webhook signatures use HMAC-SHA256:

• Signature in X-Hub-Signature-256 header
• Validated against your App Secret
• Invalid requests are rejected

Resources#

• Messenger Platform Documentation
• Meta Business Suite
• Messenger Policies