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

# Connect Facebook Messenger to ChatbotX in 5 Steps

> Connect your Facebook Page to ChatbotX, configure webhooks, set subscription fields, request advanced access, and go live with the correct permissions.

Facebook Messenger is one of the most important customer engagement channels available today. By connecting your Facebook Page to ChatbotX, you can use AI Agents to automate customer support, respond 24/7, and manage all conversations in a single unified hub — alongside WhatsApp, Instagram, and every other channel you operate.

## Prerequisites

Before you begin, make sure you have:

* A valid Facebook account
* A Facebook Page you own or administer (you need **"Full Control"** or **Admin** permissions)
* A ChatbotX installation with a publicly accessible URL (required for both the webhook callback and the OAuth callback when connecting your Page)
* Your personal Facebook account logged in on your browser (the account that manages the Page)
* If the page belongs to a Business Manager, sufficient permissions within that Business Manager

<Note>
  If you are developing locally, you need a tunneling tool such as [ngrok](https://ngrok.com/) to expose your local server to the internet.
</Note>

***

## Step 1: Create a Facebook App

<Steps>
  <Step title="Create a new app">
    Go to the [Facebook Developer Portal](https://developers.facebook.com/apps/) and click **Create App**.
  </Step>

  <Step title="Enter app details">
    Enter your **App name** and **contact email**, then click **Next**.
  </Step>

  <Step title="Select a use case">
    When asked for a use case, select **Other**.
  </Step>

  <Step title="Choose app type">
    For the app type, choose **Business**.
  </Step>

  <Step title="Finish creation">
    Review your details and click **Create App** to finish.
  </Step>

  <Step title="Get your App ID and App Secret">
    After creating your app, go to **Settings → Basic** to find your **App ID** and **App Secret**. You will need both values in the next step.
  </Step>
</Steps>

***

## Step 2: Configure Credentials in ChatbotX

A Super Admin must enter the Facebook App credentials in ChatbotX before the integration can work. Complete this step immediately after obtaining your App ID and App Secret.

<Steps>
  <Step title="Open Integrations">
    In your ChatbotX installation, navigate to:

    ```text theme={null}
    https://app.yourdomain.com/admin/platform-credentials
    ```

    Then select **Messenger**.
  </Step>

  <Step title="Open the Messenger configuration">
    Find the **Messenger** card and click the **Edit** button to open the configuration modal.
  </Step>

  <Step title="Enter your App credentials">
    Fill in the following fields using the values from the Meta Developer Portal:

    | Field                    | Description                            | Where to find it                      |
    | ------------------------ | -------------------------------------- | ------------------------------------- |
    | **App ID**               | Your Facebook **App ID**               | **Settings → Basic**                  |
    | **App Secret**           | Your Facebook **App Secret**           | **Settings → Basic** → click **Show** |
    | **Webhook Verify Token** | Random string for webhook verification | Self-generated                        |
    | **API Version**          | Facebook API version (use `v25.0`)     | **Settings → Advanced**               |
  </Step>

  <Step title="Save">
    Click **Save**. Facebook Messenger will now be available as a channel when creating chatbots.

    After saving, ChatbotX will display a **Webhook URL**. Copy and keep this URL — you will need it when configuring the webhook in Step 4.
  </Step>
</Steps>

***

## Step 3: Configure Facebook Login

<Steps>
  <Step title="Add the Facebook Login product">
    From your app dashboard, add the **Facebook Login** product.
  </Step>

  <Step title="Configure Facebook Login settings">
    In the Facebook Login settings:

    * Enable **Web OAuth Login**
    * Enable **Login with JavaScript SDK**
    * Add your self-hosted domain to **Allowed Domains for the JavaScript SDK**
  </Step>
</Steps>

***

## Step 4: Configure the Facebook App

<Steps>
  <Step title="Add your app domain">
    Under **Settings → Basic**, add your **ChatbotX installation domain** as an app domain.
  </Step>

  <Step title="Add the Messenger product">
    From the **Products** section, add **Messenger** to your app.
  </Step>

  <Step title="Configure the webhook">
    In the **Messenger settings**, configure the webhook:

    * **Callback URL**: Use the **Webhook URL** generated by ChatbotX in Step 2 (for example, `https://app.yourdomain.com/integrations/messenger/callback`)
    * **Verify Token**: Enter the **Webhook Verify Token** value you configured in the ChatbotX Integrations settings (Step 2)
  </Step>

  <Step title="Create a Messenger chatbot in ChatbotX">
    In ChatbotX, go to **Settings → Channels**, find the Messenger icon, and click **Add Messenger**. The system will redirect you to the Facebook (Meta) authentication interface:

    1. Click **Continue as \[Your Name]** to grant permissions. If you have previously connected other pages, click **Edit Settings** to ensure all new or previously unselected pages are visible.
    2. Select the Facebook Pages you want to connect and click **Continue**.
    3. Review the permissions the application is allowed to access and click **Save**.
    4. Select the radio button next to the specific Facebook Page you want to use and click **Continue**.
    5. Choose whether to sync existing contacts and up to 3 months of conversation history, or start fresh.
    6. After being redirected back to ChatbotX, confirm the correct page is displayed. Click **Test Now** to send a test message and confirm your AI Agent is working.
  </Step>
</Steps>

***

## Step 5: Test Before Going to Production

Facebook does not forward page messages to your webhook until your app is approved for production. Use the steps below to test your integration first.

<Steps>
  <Step title="Connect your Facebook Page">
    In the Messenger settings inside the Meta Developer Portal, click **Connect** next to the page you selected for your ChatbotX chatbot.
  </Step>

  <Step title="Add subscriptions">
    On the connected page, click **Add subscriptions**.
  </Step>

  <Step title="Select subscription fields">
    Subscribe to the following fields and save:

    ```text theme={null}
    messages
    messaging_postbacks
    message_reads
    message_echoes
    messaging_optins
    messaging_feedback
    messaging_referrals
    ```
  </Step>

  <Step title="Send a test message">
    Send a test message to your page from your personal Facebook account. It should appear in ChatbotX shortly after.
  </Step>

  <Step title="Verify locally (if applicable)">
    If you are running locally, confirm that requests are arriving at the `/bot` endpoint in your ngrok terminal.
  </Step>
</Steps>

***

## Going to Production

Before your app can receive messages from real users, Facebook must review and approve it.

<Steps>
  <Step title="Submit for App Review">
    Follow the [Facebook App Review](https://developers.facebook.com/docs/apps/review/) process to get your app verified.
  </Step>

  <Step title="Request advanced access">
    Request **advanced access** to the following permissions.

    **Required permissions:**

    | Permission              | Purpose                                     |
    | ----------------------- | ------------------------------------------- |
    | `pages_messaging`       | Send messages on behalf of your Page        |
    | `pages_show_list`       | List Pages available to connect in ChatbotX |
    | `pages_manage_metadata` | Subscribe webhooks on behalf of the Page    |

    **Optional permissions:**

    | Permission                | Purpose                                              |
    | ------------------------- | ---------------------------------------------------- |
    | `pages_user_gender`       | Access a user's gender via the connected Page        |
    | `pages_user_locale`       | Access a user's locale via the connected Page        |
    | `pages_user_timezone`     | Access a user's timezone via the connected Page      |
    | `pages_utility_messaging` | Send utility messages and manage messaging templates |
  </Step>
</Steps>

***

## API Version

ChatbotX supports **Facebook API v25.0**. Make sure your app is configured to use this version.

* Update the API version under **Settings → Advanced** in your Facebook app.
* Verify that your webhook subscription version is also set to **v25.0** under the app's Webhooks settings.

***

## FAQ

<AccordionGroup>
  <Accordion title="Why doesn't my Fanpage name appear in the connection list?">
    There are two common causes:

    **Access permissions** — you may only have an *Editor* or *Moderator* role. Meta requires **Admin** permissions to set up the API.

    **Missing app permissions** — you may have previously connected ChatbotX but did not select this specific page during that permission grant.

    **How to fix:** Go to your personal Facebook profile → **Settings & Privacy** → **Settings** → **Business Integrations**. Find **ChatbotX**, click **Remove**, then go back to Step 4 to start over.
  </Accordion>

  <Accordion title="I connected successfully but the AI isn't responding to customers?">
    **AI Agent configuration** — make sure you have assigned an **AI Agent** to this Messenger channel in the **AI Agent Settings**.

    **Facebook Auto-Replies** — check if the Page has Facebook's default **Instant Replies** enabled, as this feature can conflict with ChatbotX.
  </Accordion>

  <Accordion title="Does ChatbotX support managing multiple Pages at once?">
    Yes. ChatbotX is designed as an **Omnichannel** platform. You can connect multiple Facebook Pages (depending on your plan) and manage all incoming messages in a **Unified Inbox**.
  </Accordion>

  <Accordion title="How does Facebook's 24-hour rule affect the bot?">
    According to Meta's policy, bots are only allowed to respond to customers **within 24 hours of the customer's most recent message**. After 24 hours, you must use **Message Tags** or **Marketing Messages on Messenger** to continue the conversation.
  </Accordion>

  <Accordion title="How do I update permissions when I add a new Page?">
    You do not need to disconnect the existing connection. Simply repeat the **Add Messenger** process. When the Meta window appears, click **Edit Settings** and check the new Page. The system will automatically update the list without affecting previously connected pages.
  </Accordion>
</AccordionGroup>