> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/fb.md).

# Connect a Conversation Platform: FB Messenger

Connect an Agent to Messenger for a Facebook Page, including required permissions, authorization steps, and frequently asked questions

## <mark style="color:blue;">Before You Begin</mark> <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

**MaiAgent Setup**

* Create an AI Assistant on the [MaiAgent platform](https://admin.maiagent.ai/)

**Facebook Permissions**

* Your Facebook account must have been invited to a business portfolio or have created one
* You must have "full control" of that business portfolio

**Check Page Permissions**

* If the Page is already in the business portfolio: no additional changes are needed
* If the Page is not in the business portfolio: you must be a Page administrator with full control

{% hint style="info" %}
**Don't have a business portfolio yet?** Follow Meta's official instructions to [create a business portfolio](https://www.facebook.com/business/help/1710077379203657). Its creator automatically receives full control.

**How do I check whether I have full control?** In [Meta Business Suite](https://business.facebook.com/), go to <mark style="color:blue;">Settings → Users → People</mark> and click your name to view your permissions. If you only have partial access, ask a member of the portfolio with full control to adjust your permissions. See [Meta's official documentation](https://www.facebook.com/business/help/442345745885606) for details.

**Do I need to add the Page to the business portfolio first?** Not necessarily. You can claim the Page directly during authorization. If you prefer to organize it in advance, follow [Meta's official instructions](https://www.facebook.com/business/help/720478807965744) to add the Page to the portfolio.
{% endhint %}

{% hint style="warning" %}
**Is the Page already connected to another customer support system?** If the Page is connected to another app, such as Omnichat or Messenger by SHOPLINE, you must also change the default app for "Conversation routing" to MaiAgent in Meta Business Suite after connecting. Otherwise, messages will continue to be handled by the original app. See [Configure Conversation Routing for a Page Connected to Another Customer Support System](#conversation-routing). For the full migration process, see [Migrate from Another Customer Support System to MaiAgent](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/migrate-from-other-platform.md).
{% endhint %}

{% hint style="warning" %}
A Facebook Page can only be connected to one channel. To assign it to a different Agent, delete the original channel first, then reconnect it. To connect Instagram direct messages for the account linked to the same Page, create a separate [Instagram](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/instagram.md) channel.
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-d6d1aa18fa70dede47b7daeaed0a4f0eadf3febf%2Fimage%20(12)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

## <mark style="color:blue;">Set Up the Integration</mark> <a href="#start-integration" id="start-integration"></a>

### 1. Go to the Channels page in MaiAgent and click "Connect Channel" <a href="#step-go-to-maiagent-channel-page" id="step-go-to-maiagent-channel-page"></a>

a. Click <mark style="color:blue;">Connect Channel</mark> in the upper right

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-45051526831861d07352f6b1084732e923c9fa5b%2Fimage%20(102).png?alt=media" alt=""><figcaption></figcaption></figure>

b. Select Messenger

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-54c2a072dbdd6e95a23e672d6d7779e764381955%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-08-21%20122626.png?alt=media" alt=""><figcaption></figcaption></figure>

c. Click <mark style="color:blue;">Log in with Facebook</mark> and sign in with the Facebook account that manages the Page. MaiAgent only accesses messages for the Pages you authorize, not your personal messages.

{% hint style="warning" %}
Make sure your browser allows pop-ups, or the Facebook login window may be blocked.
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-dc446ea48022138a20907b9d1282def9e546042a%2Fimage%20(5)%20(1)%20(1)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

### 2. Select a business and select (claim) a Page. <a href="#step-select-business-and-page" id="step-select-business-and-page"></a>

In the Facebook authorization window, first select the business portfolio to authorize, then check the Page you want to manage (claim).

Confirm the authorization. Once creation succeeds, the Page is connected for management.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-711739d48ba4820003d4771f15abed0475eff185%2Fimage%20(13)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

### 3. Agent Settings <a href="#step-ai-agent-settings" id="step-ai-agent-settings"></a>

| Field                     | Description                                                                                                                                                                                                                                                                                                    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Channel Name**          | Give this integration a name so you can identify it easily                                                                                                                                                                                                                                                     |
| **AI Assistant**          | Select the Agent that will reply to Messenger messages                                                                                                                                                                                                                                                         |
| **Select Page**           | Select the Page you just claimed from the list in the <mark style="color:blue;">Messenger Channel</mark> section                                                                                                                                                                                               |
| **Enable Reset Commands** | (Optional) Enable this to add one or more command texts (such as "Start over"). When a user's Messenger message exactly matches one of them, a new conversation is started for that user. The command itself receives no reply; the AI responds in the new conversation when the user sends their next message |

{% hint style="info" %}
If the Page list does not update after authorization, click <mark style="color:blue;">Reload</mark> in the upper right of the <mark style="color:blue;">Messenger Channel</mark> section to authorize again.
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0bd1984760eed7ad89aaf3ddcfb63d6aaab0c98b%2Fimage%20(106).png?alt=media" alt=""><figcaption></figcaption></figure>

### 4. Verify the Integration <a href="#step-verify-integration" id="step-verify-integration"></a>

Next, try sending a test message to this channel from MaiAgent's internal conversation interface. If the Agent replies normally, the integration is successful.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1542ac8f364fb8abc6d3679953254b1d50961586%2Fimage%20(14)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

You can also open a conversation with the Agent on the Page and send a test message. If the bot replies normally, the integration is successful.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-74d2aed8c0d151071b721aba80dbfe3627258b24%2Fimage%20(10)%20(1)%20(1)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

After a successful connection, MaiAgent automatically subscribes to the Page's message events with Meta. No additional Webhook configuration is required.

{% hint style="info" %}
After connecting, click Edit in the channel list to configure additional features (OCR, using the system time or sender's name in answers, handoff to a human agent, conversation tags, access controls, and more). See [Channel Settings Overview](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/platform-settings.md).
{% endhint %}

## <mark style="color:blue;">Configure Conversation Routing for a Page Connected to Another Customer Support System</mark> <a href="#conversation-routing" id="conversation-routing"></a>

If the Page has already been connected to another customer support or marketing app (such as Omnichat or Messenger by SHOPLINE), Meta sends Messenger messages to the **default routing app** specified in "Conversation routing." When MaiAgent is not the default app, the integration may appear successful in MaiAgent, but customer messages are still handled by the original app: MaiAgent does not receive them, and the Agent does not reply.

After connecting, ask an administrator with full control of the Page to change the default app to MaiAgent in [Meta Business Suite](https://business.facebook.com/):

1. Click <mark style="color:blue;">Settings</mark> → <mark style="color:blue;">Integrations</mark> → <mark style="color:blue;">Conversation routing</mark>
2. Select this Facebook Page and click <mark style="color:blue;">Configure</mark>
3. Set <mark style="color:blue;">Default routing app</mark> to <mark style="color:blue;">MaiAgent</mark>, then click <mark style="color:blue;">Continue</mark>

Keep the following in mind:

* **Configure Messenger and Instagram separately**: Conversation routing has separate settings for the Page (Messenger) and the Instagram account. If you also want to connect Instagram direct messages, select the Instagram account on the same page and configure it separately. See [Instagram: Configure Conversation Routing](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/instagram.md#conversation-routing).
* **You do not need to remove the original app**: The default app determines which app receives conversations that no other app is currently handling. Keeping the original app does not prevent new conversations from reaching MaiAgent.
* **The change applies immediately to new conversations, but may not to ongoing ones**: After the change, messages from new customers or customers who have not interacted for a while go to MaiAgent. However, conversations already underway in the original app before the switch remain under that app's control, and subsequent messages continue to go to the original system. They move to MaiAgent only after the original app releases the conversation or the customer has not sent a message for about 24 hours (the original app may extend this period to up to 7 days). Earlier messages and conversation history remain in the original system and are not transferred.
* **Ads and dedicated links may have separate assignments**: If the original app assigned a handling app to click-to-Messenger ads or m.me links, conversations entering through those sources may still go to the original app regardless of the default app. Change the assignment to MaiAgent in the original app or ad settings, or disable those entry points first.
* **Verify each scenario after switching**: Test a new conversation using an account that has never messaged the Page. Keep checking the original system for a few days around the switch to ensure follow-up messages in ongoing conversations are handled. For active ads or links, send a message through each entry point and confirm it reaches MaiAgent. If ongoing conversations must move immediately, ask the original system's provider to release or hand them over.
* **Roll back**: Change the default routing app back to the original app. As with the initial switch, rollback takes effect immediately only for new conversations and conversations that have been inactive for a while. Follow-up messages in conversations already underway in MaiAgent will still arrive in MaiAgent until about 24 hours of inactivity have passed. Have your support team continue replying in MaiAgent during this time. You can keep the MaiAgent channel in place; to switch back to it later, simply repeat this step.

For example, an online store's Page was originally connected to Omnichat. After connecting Messenger in MaiAgent, the administrator sends a test message from their personal account. Nothing appears in MaiAgent's <mark style="color:blue;">All Conversations</mark>, but Omnichat receives it. In Business Suite's <mark style="color:blue;">Conversation routing</mark>, the default routing app is still Omnichat. After changing it to MaiAgent, the administrator sends another message from a different account that has never messaged the Page, and it arrives in MaiAgent. However, follow-up messages from customers already talking with support in Omnichat still go to Omnichat. The support team finishes replying to those customers in Omnichat that day; when they check the next day, messages are all arriving in MaiAgent.

{% hint style="info" %}
The English interface calls this setting "Conversation routing." The reminder on MaiAgent's channel settings page refers to it as "conversation routing" as well. Menu locations may change as Meta updates its interface; see Meta's official [Conversation Routing](https://developers.facebook.com/docs/messenger-platform/conversation-routing) documentation for how it works. Before changing the setting, note the original default app (including if none was set), so you can restore it if needed.
{% endhint %}

## <mark style="color:blue;">Supported Message Types</mark> <a href="#supported-message-types" id="supported-message-types"></a>

| Direction    | Supported Content                                                                 |
| ------------ | --------------------------------------------------------------------------------- |
| User → Agent | Text, images, videos, voice messages, stickers; images can be recognized with OCR |
| Agent → User | Text, images                                                                      |

* **Automatic conversion of Markdown to plain text**: Messenger does not render Markdown. Headings, bold and italic text, links, tables, and other Markdown syntax in Agent replies are automatically converted to plain text before sending (links become "text URL"). Text entered by human support agents is unaffected. See [Message Rendering Improvements: Messaging Channels](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat/markdown-rendering.md#messaging-channels-plain-text)
* **Consecutive messages are combined into one turn**: When a user sends several images in a row, or sends an image followed by text, the Agent waits for the sequence to arrive before replying once. For image-only messages, it replies after about 4 seconds without a new message following the last one, with a maximum wait of about 20 seconds; receiving text triggers an immediate reply. Only one turn is processed at a time in each conversation
* **24-hour reply window**: Meta only allows replies within 24 hours of the user's last message. Messages sent after this window are marked [Not Delivered](https://docs.maiagent.ai/maiagent-user-guide/en/serve/daily-operations/reply.md#delivery-failed) on the conversation page
* **Button events do not currently reach MaiAgent**: When a customer clicks Messenger's "Get Started" button or a menu button, Meta sends a button event (postback), not a regular message. These events do not currently enter MaiAgent, appear in conversations, or trigger Agent replies. Messages customers type are unaffected. For example, if the Page had a "Get Started" welcome flow in the previous system, new customers clicking "Get Started" after migration to MaiAgent receive no response, and no entry appears in the conversation history. Once they type a question, their message arrives normally

## <mark style="color:blue;">Frequently Asked Questions</mark> <a href="#faq" id="faq"></a>

### Q: Why is the Page list empty after authorization? <a href="#faq-empty-page-list" id="faq-empty-page-list"></a>

The Facebook account you used does not have full control of the Page, or you did not select the Page during authorization. Check permissions using [Before You Begin](#pre-integration-checklist), then sign in again as a Page administrator and make sure the correct Page is checked in the authorization window.

### Q: Why does saving show "This Page ID is already in use"? <a href="#faq-page-already-used" id="faq-page-already-used"></a>

The same Facebook Page is already connected to another channel in your organization. Delete the original channel first, then create it again.

### Q: A user sent a message, but MaiAgent did not receive it. Why? <a href="#faq-no-incoming-message" id="faq-no-incoming-message"></a>

If the Page was connected to another customer support system, first check that the default routing app in Meta Business Suite's <mark style="color:blue;">Conversation routing</mark> is MaiAgent. See [Configure Conversation Routing](#conversation-routing). If MaiAgent is already the default but still receives nothing, the customer may have been in a conversation controlled by the old system before the switch, or may have entered through an ad or link assigned to the old system. Test again using an account that has never messaged the Page.

Then confirm that the authorized Facebook account is still a Page administrator and that the Page is still in the business portfolio selected during authorization. If authorization has expired or Page permissions have been removed, delete the channel and reconnect it.

### Q: Why do customers still receive automatic messages such as "Our team will reply during business hours"? <a href="#faq-meta-auto-reply" id="faq-meta-auto-reply"></a>

These messages come from Meta Business Suite's built-in automated responses and do not pass through MaiAgent, so they do not appear in MaiAgent's <mark style="color:blue;">All Conversations</mark>. Disabling MaiAgent's AI automatic reply schedule does not stop them either. Pages migrated from other customer support systems often retain these previously configured messages.

In Meta Business Suite, go to <mark style="color:blue;">Inbox</mark> → <mark style="color:blue;">Automations</mark> and review <mark style="color:blue;">Away message</mark>, <mark style="color:blue;">Instant reply</mark>, <mark style="color:blue;">Frequently asked questions</mark>, and <mark style="color:blue;">Leads</mark> one by one. Turn off those you no longer need, and update any you want to keep to reflect your current setup.

For example, after a brand switches to human support only, its support team notices that customers messaging at night still immediately receive "Our team will reply during business hours," but this message does not appear in MaiAgent's conversation history. This is Business Suite's away message. Turn it off under <mark style="color:blue;">Inbox</mark> → <mark style="color:blue;">Automations</mark> to stop it. Automated responses for Instagram direct messages are configured in the same place.

### Q: Can Messenger and Instagram share the same Agent? <a href="#faq-share-agent" id="faq-share-agent"></a>

Yes. They are separate channels that can be linked to the same Agent, and each can have its own feature settings. For Instagram integration, see [Connect a Messaging Channel: Instagram](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/instagram.md).

### Q: How do I remove (disconnect) Messenger? <a href="#faq-disconnect" id="faq-disconnect"></a>

In the <mark style="color:blue;">Channels</mark> list, click <mark style="color:blue;">Delete</mark> in the actions column for the Messenger channel and confirm (the icon is disabled if you do not have delete permission). Once deleted, MaiAgent stops receiving and replying to messages for this Page. If you need to keep the conversation history, export it from <mark style="color:blue;">All Conversations</mark> first. MaiAgent does not revoke your Facebook authorization for you. To fully disconnect, also remove authorization for the MaiAgent app in the Page's settings. To reconnect later, repeat [Set Up the Integration](#start-integration).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/fb.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
