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

# Configure Facebook Messenger

> Learn how to create a Facebook App and configure credentials to connect the Messenger channel on your portal.

Creating your own Facebook Messenger app allows you to customize the permission screen to show your own brand name and logo when customers connect their Facebook Pages.

## Prerequisites

Before you begin, make sure you have:

* A valid Facebook account
* A Facebook Page you own or administer
* Super Admin access to your portal to input configurations

<Note>
  If you are developing locally, you will need a tunneling tool such as ngrok to expose your local server to the internet to receive Facebook webhooks.
</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**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/6419eoAF_uo2OCBi/images/image-1.png?fit=max&auto=format&n=6419eoAF_uo2OCBi&q=85&s=a4312497d6e27a9d63e2c2adc4fd6d12" alt="Create App button in the Facebook Developer Portal" width="2409" height="757" data-path="images/image-1.png" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/bk1D42eDWTivbgT_/images/image-2.png?fit=max&auto=format&n=bk1D42eDWTivbgT_&q=85&s=5249012405fdb92ea7cadc59bbcd09ce" alt="App name and contact email fields" width="2197" height="937" data-path="images/image-2.png" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/bk1D42eDWTivbgT_/images/image-3.png?fit=max&auto=format&n=bk1D42eDWTivbgT_&q=85&s=bbd6313775d17a3971de57329c78c56f" alt="Use case selection - Other option highlighted" width="2151" height="1708" data-path="images/image-3.png" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/bk1D42eDWTivbgT_/images/image-4.png?fit=max&auto=format&n=bk1D42eDWTivbgT_&q=85&s=a7bc6f433111bee494f0220d8505799c" alt="App type selection - Business option highlighted" width="2173" height="844" data-path="images/image-4.png" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/bk1D42eDWTivbgT_/images/image-5.png?fit=max&auto=format&n=bk1D42eDWTivbgT_&q=85&s=5d530bddb2eeb78f5d24962a31fcfbb1" alt="Confirmation screen before creating the app" width="2177" height="1104" data-path="images/image-5.png" />
    </Frame>
  </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.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/bk1D42eDWTivbgT_/images/image-6.png?fit=max&auto=format&n=bk1D42eDWTivbgT_&q=85&s=0d075ac6d3a6ff00f748941fa54aecfa" alt="App ID and App Secret in Basic Settings" width="2529" height="1463" data-path="images/image-6.png" />
    </Frame>
  </Step>
</Steps>

## Step 2: Configure Credentials in the Admin Portal

You must enter the Facebook App credentials in the Admin Portal to enable the Messenger connection feature for your customers.

<Steps>
  <Step title="Open Integrations">
    Log in to your Admin Portal, navigate to:

    ```text theme={null}
    https://app.chatconnectx.com/manage/integrations
    ```

    Then select **Messenger**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/FAZvdFXI0s4AXKUI/images/image-322.png?fit=max&auto=format&n=FAZvdFXI0s4AXKUI&q=85&s=2edc84c2d2a32733331b5db852f8e7f1" alt="chatbotx_super_admin_integrations_messenger" width="2822" height="1045" data-path="images/image-322.png" />
    </Frame>
  </Step>

  <Step title="Enter your App credentials">
    <Frame>
      <img src="https://mintcdn.com/chatbotx/rIKY9dgGT5yHSIxP/images/image-328.png?fit=max&auto=format&n=rIKY9dgGT5yHSIxP&q=85&s=cee094d7a43f806364a77b5ed6440ed3" alt="chatbotx_super_admin_messenger_edit_modal" width="2818" height="1603" data-path="images/image-328.png" />
    </Frame>

    Fill in the 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**. The Messenger channel will now be ready for your customers to connect.

    After saving, the system will display a **Webhook URL**. Copy this URL to use in Step 4.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/rIKY9dgGT5yHSIxP/images/image-330.png?fit=max&auto=format&n=rIKY9dgGT5yHSIxP&q=85&s=2666e268d36ba3ab2e6c125264324925" alt="chatbotx_super_admin_messenger_overview" width="1063" height="853" data-path="images/image-330.png" />
    </Frame>
  </Step>
</Steps>

## Step 3: Configure Facebook Login

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/bk1D42eDWTivbgT_/images/image-7.png?fit=max&auto=format&n=bk1D42eDWTivbgT_&q=85&s=e5ee48883c0776c04347d3fe6d7507fd" alt="Adding Facebook Login product" width="2696" height="1624" data-path="images/image-7.png" />
    </Frame>
  </Step>

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

    * Enable **Web OAuth Login**
    * Enable **Login with JavaScript SDK**
    * Add your portal domain to **Allowed Domains for the JavaScript SDK** (e.g., `app.chatconnectx.com`)

    <Frame>
      <img src="https://mintcdn.com/chatbotx/NoN3HsGeD9DrrbW9/images/image-8.png?fit=max&auto=format&n=NoN3HsGeD9DrrbW9&q=85&s=4af3722cd173edcb28ab3d7feb371c87" alt="Facebook Login settings with OAuth and SDK options" width="2669" height="1564" data-path="images/image-8.png" />
    </Frame>
  </Step>
</Steps>

## Step 4: Configure Webhooks on the Facebook App

<Steps>
  <Step title="Add your app domain">
    Under **Settings → Basic**, add your portal domain (e.g., `app.chatconnectx.com`) as an app domain.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/FAZvdFXI0s4AXKUI/images/image-323.png?fit=max&auto=format&n=FAZvdFXI0s4AXKUI&q=85&s=9bc27b198f617cdfcb73c6d9e75ef723" alt="App domain field in Basic Settings" width="2681" height="1466" data-path="images/image-323.png" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/6419eoAF_uo2OCBi/images/image-10.png?fit=max&auto=format&n=6419eoAF_uo2OCBi&q=85&s=829b378ce1e22dc809aaef8ee7f09688" alt="Adding Messenger product" width="2658" height="1389" data-path="images/image-10.png" />
    </Frame>
  </Step>

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

    * **Callback URL**: Use the **Webhook URL** generated by the Admin Portal in Step 2 (e.g., `https://app.chatconnectx.com/integrations/messenger/callback`)
    * **Verify Token**: Enter the **Webhook Verify Token** value you configured in the Admin Portal (Step 2)

    <Frame>
      <img src="https://mintcdn.com/chatbotx/6419eoAF_uo2OCBi/images/image-11.png?fit=max&auto=format&n=6419eoAF_uo2OCBi&q=85&s=094f4deb374d361b7db9aba05945f0aa" alt="Webhook callback URL and verify token fields" width="3496" height="1602" data-path="images/image-11.png" />
    </Frame>
  </Step>
</Steps>

## Step 5: Test before Going to Production

Meta does not forward page messages to your webhook until your app is approved Live. You need to add a tester account to verify it first.

<Steps>
  <Step title="Connect your Facebook Page">
    In the Messenger settings of the Facebook App, click **Connect** next to the page you want to use for testing.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/6419eoAF_uo2OCBi/images/image-12.png?fit=max&auto=format&n=6419eoAF_uo2OCBi&q=85&s=a2bd96971dbd733dc833c53db936c15f" alt="Connect button for a Facebook Page" width="3493" height="1738" data-path="images/image-12.png" />
    </Frame>
  </Step>

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

    <Frame>
      <img src="https://mintcdn.com/chatbotx/6419eoAF_uo2OCBi/images/image-13.png?fit=max&auto=format&n=6419eoAF_uo2OCBi&q=85&s=872b34c843aa3e331c8ae96824310a1f" alt="Add subscriptions button" width="3494" height="1667" data-path="images/image-13.png" />
    </Frame>
  </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
    ```

    <Frame>
      <img src="https://mintcdn.com/chatbotx/6419eoAF_uo2OCBi/images/image-14.png?fit=max&auto=format&n=6419eoAF_uo2OCBi&q=85&s=6f3ec2731d58c80336346d4299b34951" alt="Subscription fields selection" width="3493" height="1666" data-path="images/image-14.png" />
    </Frame>
  </Step>

  <Step title="Send a test message">
    Send a test message to your page from a personal Facebook account (which has Admin/Tester role in the app). It should appear in your portal.
  </Step>
</Steps>

## Going to Production

Before your app can receive messages from real users, Meta 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 permissions below:

    **Required permissions**

    | Permission              | Purpose                                  |
    | :---------------------- | :--------------------------------------- |
    | `pages_messaging`       | Send messages on behalf of your Page     |
    | `pages_show_list`       | List Pages available to connect          |
    | `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

The system 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**.

<Frame>
  <img src="https://mintcdn.com/chatbotx/6419eoAF_uo2OCBi/images/image-15.png?fit=max&auto=format&n=6419eoAF_uo2OCBi&q=85&s=c712e3bfdb1ead8872642c65b20c3bef" alt="API version setting in Advanced Settings" width="3567" height="825" data-path="images/image-15.png" />
</Frame>

## User Connection Guide

After completing the app configuration on the Meta Developer Portal and entering the Credentials in the Admin Portal, your customers can connect their Facebook Pages.

For step-by-step instructions, see the [Facebook Messenger Connection Guide](/channels/messenger/connect-facebook-messenger).