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

# Messenger and Facebook

> Add your bot to Messenger and Facebook using the official integration

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01KPDRM4RJN85JM6DRP43W48PX)
*v5.1.8*

The official Messenger and Facebook integration allows users to chat with your bot by messaging a Facebook page.

## Setup

> [tab] Basic configuration
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Facebook page](https://www.facebook.com/pages/create/)
>
> 1. In Botpress Studio, select \*\* Explore Hub\*\* in the upper-right corner.
> 2. Search for the **Messenger** integration, then select **Install Integration**.
> 3. In the **Configuration** menu, select **Authorize Messenger**.
> 4. Follow the instructions to connect Botpress to your Messenger account.

> [tab] Manual configuration
>
> For advanced use cases, you can use your own Meta app with our integration.
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Facebook page](https://www.facebook.com/pages/create/)
> > * A [Meta developer app](https://developers.facebook.com/apps/creation/). Check out the [Meta developer documentation](https://developers.facebook.com/docs/development/create-an-app) to learn more about the setup process.
>
> ### Get your Meta app ready
>
> Before setting up the integration in Botpress, you need to get your Meta app ready:
>
> **1. Add the Messenger API**
>
> To configure your integration, you need to access the Messenger API:
>
> 1. Log in to your [Meta developer account](https://developers.facebook.com/apps/).
> 2. Select the app you want to use with the integration.
> 3. Scroll to **Add products to your app**.
> 4. Under the **Messenger** section, select **Set up**.
>
> **2. Add your Facebook page**
>
> To add your Facebook page to the Messenger API configuration:
>
> 1. In your Meta app's left sidebar, go to **Messenger > Messenger API Settings**.
> 2. Scroll to **Generate access tokens**, then select **Connect**.
> 3. Follow the on-screen instructions to add your Facebook page.
>
> **3. Check your API version**
>
> Next, check that your API version is 15.0 or higher:
>
> 1. In your Meta app's left sidebar, go to **App settings > Advanced**.
> 2. In the **Upgrade API version** section, make sure the version is 15.0 or higher.
> 3. If you updated the version, select **Save changes** in the bottom-right corner.
>
> ### Set up the integration in Botpress
>
> [Once your Meta app is ready](#get-your-meta-app-ready), you can set up the integration in Botpress:
>
> **1. Install the integration**
>
> 1. In Botpress Studio, select \*\* Explore Hub\*\* in the upper-right corner.
> 2. Search for the **Messenger and Facebook** integration, then select **Install Integration**.
> 3. In the **Configuration** menu, select the drop-down menu, then select **Configure by manually supplying the Meta app details**.
>
> **2. Configure the integration**
>
> To configure the integration, you need to create a webhook endpoint for the Messenger integration. To do this, fill in the integration's configuration fields using information from your Meta app:
>
> > [accordion] Client ID
> >
> > To get your Meta app's client ID:
> >
> > 1. In your Meta app's left sidebar, go to **App settings > Basic**.
> > 2. Copy the **App ID**, then paste it in the **Client ID** field in Botpress.
>
> > [accordion] Client Secret (Optional)
> >
> > > [!NOTE]
> > >
> > > The client secret is used to check the webhook's signature. You can leave this field empty to disable signature check.
> >
> > To get your Meta app's client secret:
> >
> > 1. In your Meta app's left sidebar, go to **App settings > Basic**.
> > 2. Copy the **App secret**, then paste it in the **Client Secret** field in Botpress.
>
> > [accordion] Verify Token
> >
> > Used by Meta to verify that you’re the real owner of the provided webhook. Can be any alphanumeric string.
>
> > [accordion] Access Token
> >
> > To get your Meta app's access token:
> >
> > 1. In your Meta app's left sidebar, go to **Messenger > Messenger API Settings**.
> > 2. Scroll to **Generate access tokens**, then find your Facebook page.
> > 3. Select **Generate**, then copy the token.
> > 4. Paste it into the **Access Token** field in Botpress.
>
> > [accordion] Page ID
> >
> > To get your Meta app's page ID:
> >
> > 1. In your Meta app's left sidebar, go to **Messenger > Messenger API Settings**.
> > 2. Scroll to **Generate access tokens**, then find your Facebook page.
> > 3. Copy the number under your page's name, then paste it into the **Page ID** field in Botpress.
>
> When you’ve filled in all the fields, select **Save Configuration**. This will automatically enable your integration.
>
> ### Finalize the integration
>
> Now that your Botpress webhook endpoint is ready, you can add it to your Meta app:
>
> **1. Get the webhook URL and Verify Token**
>
> In Botpress, copy:
>
> * The integration's webhook URL. It should start with `https://webhook.botpress.cloud/`
> * The **Verify Token** you created
>
> **2. Configure the webhook in Meta**
>
> 1. Go back to your Meta app. In the left sidebar, go to **Messenger > Messenger API Settings**.
>
> 2. Scroll to **Configure webhooks**
>
> 3. Paste:
>    * Your webhook URL into the **Callback URL** field.
>    * Your **Verify Token** into the **Verify token** field.
>
> 4. Select **Verify and save**.
>
> > [!NOTE]
> >
> > Make sure you saved your integration's configuration after [configuring it in Botpress](#set-up-the-integration-in-botpress)—otherwise, the webhook validation will fail.
>
> **3. Subscribe to webhook fields**
>
> Under **Webhook fields**, subscribe to:
>
> * `messages`
> * `messaging_postbacks`
> * `feed`
>
> ### Submit app for review
>
> The integration is configured, but will only work for admins, developers, and testers. To make it available for public use, make sure you [submit it for review by Meta](https://developers.facebook.com/docs/resp-plat-initiatives/individual-processes/app-review/submission-guide).
>
> > [!TIP]
> >
> > You've manually configured your Messenger integration.

> [tab] Playground
>
> If you want to test your bot's behaviour in Messenger before going through the actual setup process, you can use the Messenger integration playground.
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> > * A [Facebook account](https://www.facebook.com/r.php?entry_point=login)
>
> 1. In Botpress Studio, select \*\* Explore Hub\*\* in the upper-right corner.
> 2. Search for the **Messenger** integration, then select **Install Integration**.
> 3. Select **Test your agent on Messenger**.
> 4. Follow the instructions to set up the playground.

***

## Options

The Messenger integration's **Configuration** menu offers a few additional options:

### Get user profile

When this option is enabled (default), the integration will update the Botpress user's name and picture URL with data from Messenger.

> [!NOTE]
>
> This option is only available with [manual configuration](#manual-configuration).

### Download media

When enabled, this option automatically downloads media files using the [Files API](https://botpress.com/docs/api-reference/files-api/getting-started.md). When disabled, media files are displayed using their Messenger media URL.

### Downloaded media expiry

Expiry time (in hours) for downloaded media files. An expiry time of 0 means the files will never expire. Defaults to 24 hours.

***

## Replying to comments in DM

You can configure your bot to reply to user comments in a direct message (DM).

### Step 1: Check where the conversation started

First, add a router Node that checks whether the conversation originated from a user's comment.

**Step 1**

In Botpress Studio, enter your [Main Workflow](https://botpress.com/docs/studio/concepts/workflows.md#main).

**Step 2**

[Add a new Node](https://botpress.com/docs/studio/concepts/nodes/introduction.md#add-a-node) to the Workflow.

**Step 3**

Rename the Node to `Router`, then move it between the [Start Node](https://botpress.com/docs/studio/concepts/nodes/introduction.md) and any other existing Nodes:

![Reply to comments in DMs 1](https://mintcdn.com/botpress/nGxtuPRsB_zQCzqJ/integrations/integration-guides/assets/messenger-reply-in-dm-1.png?fit=max\&auto=format\&n=nGxtuPRsB_zQCzqJ\&q=85\&s=048493cedeca8d131076290eec4c380e)

**Step 4**

Add two [Expression Cards](https://botpress.com/docs/studio/concepts/cards/flow-logic.md#expression) to the `Router` Node.

**Step 5**

Open the second Expression Card's [inspector](https://botpress.com/docs/studio/concepts/cards/introduction.md#configure-a-card). Next to the **Condition** field, toggle Magic icon to disable generative AI.

**Step 6**

Configure this Card for conversations started normally:

* In the **Label** field, paste in: `Conversation started`
* In the **Condition** field, paste in: `{{event.channel == 'channel'}}`

**Step 7**

Open the first Expression Card's [inspector](https://botpress.com/docs/studio/concepts/cards/introduction.md#configure-a-card). Next to the **Condition** field, toggle Magic icon to disable generative AI.

**Step 8**

Configure this Card for conversations started from a comment reply:

* In the **Label** field, paste in: `Conversation started from comment`
* In the **Condition** field, paste in: `{{event.channel == 'commentReplies'}}`

**Step 9**

Attach the Start Node to the `Router` Node. Then, attach the `Conversation started` Expression Card to your regular conversation logic:

![Reply to comments in DMs 2](https://mintcdn.com/botpress/nGxtuPRsB_zQCzqJ/integrations/integration-guides/assets/messenger-reply-in-dm-2.png?fit=max\&auto=format\&n=nGxtuPRsB_zQCzqJ\&q=85\&s=3c074defdb709d2128db3fdfe4ea8fe4)

### Step 2: Reply to the user's comment

Next, add logic to reply to the user's comment. This lets them know that the bot will continue the conversation in a DM.

**Step 1**

Add a new Node to your Workflow and rename it to `Reply_to_comment`.

**Step 2**

Add a [Text Card](https://botpress.com/docs/studio/concepts/cards/send-messages.md#text) to the new Node.

**Step 3**

Open the Text Card's inspector.

In the **Message to send** field, enter the message you want to reply to the user's comment. For example: `Check your DMs!`.

**Step 4**

Attach the `Conversation started from comment` Expression Card to the `Reply_to_comment` Node:

![Reply to comments in DMs 3](https://mintcdn.com/botpress/nGxtuPRsB_zQCzqJ/integrations/integration-guides/assets/messenger-reply-in-dm-3.png?fit=max\&auto=format\&n=nGxtuPRsB_zQCzqJ\&q=85\&s=7afbec25cbaad43928ac50a56188e011)

### Step 3: Start a DM conversation from the comment

Finally, add logic to start a DM conversation whenever a user leaves a comment.

**Step 1**

Add a new Node to your Workflow and rename it to `DM_reply`.

**Step 2**

Add the [Start DM Conversation from Comment](#start-dm-conversation-from-comment) Card to the new Node.

**Step 3**

Open the Start DM Conversation from Comment Card's inspector.

* In the **Comment ID** field, paste in: `{{event.payload.commentId}}`
* In the **Message** field, enter the first message you want to send the user in a DM. For example: `Hey! Received your comment.`

> [!NOTE]
>
> If you want to send the user's original comment back to them, you can add `{{event.payload.text}}` to the **Message** field.

**Step 4**

Attach the `Reply_to_comment` Node to the `DM_reply` Node. Then, attach the `DM_reply` Node to the [End Node](https://botpress.com/docs/studio/concepts/nodes/introduction.md#end):

![Reply to comments in DMs 4](https://mintcdn.com/botpress/nGxtuPRsB_zQCzqJ/integrations/integration-guides/assets/messenger-reply-in-dm-4.png?fit=max\&auto=format\&n=nGxtuPRsB_zQCzqJ\&q=85\&s=96e33b736c17398356526ee1ba9f34ff)

> [!TIP]
>
> When a user comments on a post, your bot will now:
>
> * Reply to their comment, letting them know to check their DMs
> * Continue the conversation in a DM
>
> You can further modify your Workflow depending on your desired behaviour.

***

## Cards

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### Get or Create a Conversation

Proactively create a conversation from a bot

**input** `object`

**conversation** `object` *required*

The conversation object fields

**userId** `string` *required*

The Messenger user ID of the user in the conversation

**commentId** `string`

The Messenger ID of the comment for which the private-reply conversation should be created

**output** `object`

**conversationId** `string` *required*

The Botpress ID of the created conversation

### Get or Create a User

Proactively create a user from a bot

**input** `object`

**name** `string`

The name of the user

**pictureUrl** `string`

The URL of the user profile picture

**email** `string`

The email of the user

**user** `object` *required*

The user object fields

**id** `string` *required*

The Messenger ID of the user

**output** `object`

**userId** `string` *required*

The Botpress ID of the created user

### Start DM Conversation from Comment

Start a DM conversation from a comment

**input** `object`

**commentId** `string` *required*

The ID of the comment to start the conversation from

**message** `string` *required*

The message to send to the user

**output** `object`

This Card has no output.

***

## Tags

You can read [event tags](https://botpress.com/docs/studio/guides/advanced/event-properties.md#param-tags) to get information about an active Messenger conversation:

### Message ID

To get the Messenger ID of a message:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.message["messenger:id"]
```

### Recipient ID

To get the Messenger ID of the recipient:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.message["messenger:recipientId"]
```

### Sender ID

To get the Messenger ID of the sender:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.message["messenger:senderId"]
```

### Conversation ID

To get the Messenger ID of the conversation:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.conversation["messenger:id"]
```

### User ID

To get the Messenger ID of the user:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event.tags.user["messenger:id"]
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.