> ## 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.

# Facebook Messenger

> Connect Facebook Messenger to ChatbotX so your chatbot can send and receive messages on your Facebook Page.

## Prerequisites

Before you begin, make sure you have:

* A valid Facebook account
* A Facebook Page you own or administer
* A ChatbotX installation with a publicly accessible URL (required for both the webhook callback and the OAuth callback when connecting your Page)

<Info>
  If you are developing locally, you will need a tunneling tool such as [ngrok](/channels/local-development-with-tunnels) to expose your local server to the internet.
</Info>

## 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 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/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 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.

    <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 self-hosted domain to **Allowed Domains for the JavaScript SDK**

    <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 the Facebook App

<Steps>
  <Step title="Add your app domain">
    Under **Settings → Basic**, add your **ChatbotX installation domain** 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 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)

    <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>

  <Step title="Create a Messenger chatbot in ChatbotX">
    In ChatbotX, create a Messenger chatbot and select the Facebook Page you want to connect. See [Connect Facebook Messenger](/channels/messenger/connect-facebook-messenger) for step-by-step instructions.
  </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, click **Connect** next to the page you selected for your ChatbotX chatbot.

    <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 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 permissions below:

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

<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>