> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Facebook Messenger

> Connect AGO agents with Facebook Messenger for customer interactions

This documentation describes the Facebook Messenger integration with AGO, allowing your customers to interact with AGO agents directly from Facebook Messenger.

## Overview

The Facebook Messenger integration supports:

* Receiving messages from your Facebook Pages
* Message processing by AGO agents
* Text messages with support for long responses (auto-split at 2000 characters)
* Media messages (images, documents, audio, video)
* Secure webhook validation with HMAC-SHA256

## Prerequisites

Before setting up the integration, you need:

1. **Facebook Page**: A Facebook Page that you manage with admin access
2. **OAuth Link**: A connection link provided by the AGO team

## Setup Guide

<Steps>
  <Step title="Request Access from AGO Team">
    Contact the AGO team to receive your OAuth connection link. This link will allow you to authorize your Facebook Page to work with AGO.
  </Step>

  <Step title="Authorize Your Facebook Page">
    1. Click on the OAuth link provided by AGO
    2. Log in to Facebook if not already logged in
    3. Select the Facebook Page(s) you want to connect
    4. Grant the required permissions (messaging permissions)
    5. Complete the authorization flow
  </Step>

  <Step title="Verify the Connection in AGO">
    1. Log in to your AGO Admin panel
    2. Navigate to **Settings > Integrations > Messenger**
    3. Your connected page(s) should appear in the list
    4. Verify the connection status shows "Connected"
  </Step>

  <Step title="Assign an Agent (Optional)">
    1. In the Messenger integration page, find your connected page
    2. Click **Assign Agent**
    3. Select the agent that should handle messages from this page
    4. Click **Update Agent**
  </Step>
</Steps>

## Supported Message Types

### Incoming Messages (From Users)

| Type    | Description                    |
| ------- | ------------------------------ |
| Text    | Plain text messages            |
| Image   | Photos with optional captions  |
| Audio   | Voice messages and audio files |
| Video   | Video messages                 |
| Sticker | Sticker images                 |

### Outgoing Messages (From AGO)

| Type | Description                                                   |
| ---- | ------------------------------------------------------------- |
| Text | Plain text up to 2000 characters (longer messages auto-split) |

## Features

### Long Message Handling

Facebook Messenger has a 2000 character limit per message. AGO automatically splits longer responses intelligently:

* Prioritizes splitting at paragraph breaks
* Falls back to sentence endings
* Then word boundaries

### Agent Assignment

You can assign specific agents to each Facebook Page:

* Messages are routed to the assigned agent
* If no agent is assigned, the default agent handles messages
* Change agent assignments anytime in the admin panel

### Message Queuing

When users send multiple messages rapidly (within 2 seconds), AGO:

* Queues the messages
* Merges them into a single request
* Provides a unified response

This prevents fragmented conversations and improves response quality.

### Human Takeover Detection

AGO automatically detects when a human operator responds on the Facebook Page:

* If a human replies from the Page, AGO pauses automated responses
* This prevents duplicate or conflicting responses
* Normal operation resumes when the human conversation ends

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues">
    **Page Not Appearing After Authorization**

    * Ensure you have admin access to the Facebook Page
    * Try the authorization flow again
    * Contact AGO support if the issue persists

    **Messages Not Being Processed**

    * Check that the page is marked as "Connected" in AGO
    * Verify an agent is assigned to the page
  </Accordion>

  <Accordion title="Checking Connection Status">
    1. Go to **Settings > Integrations > Messenger**
    2. Check the status badge on each page:
       * **OAuth Connected**: Page is working
       * **Webhook Active**: Webhook is properly receiving events
       * **Webhook Inactive**: Contact AGO support
  </Accordion>
</AccordionGroup>

## Security

The Messenger integration includes several security measures:

* **Webhook Signature Validation**: All incoming webhooks are validated using HMAC-SHA256
* **Encrypted Token Storage**: Page access tokens are encrypted at rest
* **OAuth Flow**: Secure authorization via Facebook's official OAuth flow

## Limitations

* Only one AGO tenant can connect each Facebook Page (unique constraint)
* Interactive message templates are not currently supported
* Only text responses are supported (no images or documents from AGO)

## Support

If you encounter issues:

1. Check the troubleshooting section above
2. Contact the AGO team with your Page name and any error messages