Skip to content

feat: rewrite messenger guide #299

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 9, 2025
Merged

feat: rewrite messenger guide #299

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39b68fd
wip
adkah Oct 8, 2025
bc67b6f
feat: rewrite messenger guide
adkah Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed integrations/integration-guides/assets/messenger.png
View file
Open in desktop
Binary file not shown.
307 changes: 230 additions & 77 deletions integrations/integration-guides/messenger.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
title: Messenger
description: Add your bot to Messenger using the official integration
icon: '/integrations/integration-guides/assets/icons/messenger.svg'
---

Expand All @@ -11,118 +12,270 @@ import Cards from '/snippets/integrations/cards/botpress/messenger.mdx'

<OpenInHub integration={integrationVersions.messenger}/>


import { YouTube } from '/snippets/youtube.mdx'

{/* vale on */}

<img src="./assets/messenger.png" />

<br />

<YouTube url="https://www.youtube.com/embed/pOIrLMpZZqc?si=98JjAEk6hnSEiKZ2" />

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

* A [Meta developer app](https://developers.facebook.com/apps/create/) that will serve as the primary platform for managing connection between Messenger and Botpress, including the configuration of webhooks and access tokens.
* A [Facebook page](https://www.facebook.com/pages/create/) that you own or has the developer role, this is needed to use the Messenger API.
* A [Botpress Cloud account](https://sso.botpress.cloud) and a [Botpress Bot](/learn/get-started/quick-start)
## Setup

<Tabs>
<Tab title="Basic configuration">

<Info>
You will need:

- A [published bot](/learn/get-started/quick-start)
- A [Facebook page](https://www.facebook.com/pages/create/)
</Info>

1. In Botpress Studio, select **<Icon icon="boxes"/> 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>
<Tab title="Manual configuration">
For advanced use cases, you can use your own Meta app with our integration.

<Info>
You will need:

- A [published bot](/learn/get-started/quick-start)
- 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.
</Info>

### Get your Meta app ready

Before setting up the integration in Botpress, you need to get your Meta app ready:

<Steps>
<Step title="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**.
</Step>
<Step title="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.
</Step>
<Step title="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.
</Step>
</Steps>

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

<Steps>
<Step title="Install the integration">

1. In Botpress Studio, select **<Icon icon="boxes"/> Explore Hub** in the upper-right corner.
2. Search for the **Messenger** 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**.

</Step>
<Step title="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:

<AccordionGroup>
<Accordion
title="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>
<Accordion
title="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.
</Note>

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>
<Accordion
title="Verify Token"
>
Used by Meta to verify that you’re the real owner of the provided webhook. Can be any alphanumeric string.
</Accordion>
<Accordion
title="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>
<Accordion
title="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.
</Accordion>
</AccordionGroup>

When you’ve filled in all the fields, select **Save Configuration**. This will automatically enable your integration.
</Step>
</Steps>

### Finalize the integration

Now that your Botpress webhook endpoint is ready, you can add it to your Meta app:

<Steps>
<Step title="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
</Step>
<Step title="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.
</Note>
</Step>
<Step title="Subscribe to webhook fields">
Under **Webhook fields**, subscribe to `messages` and `messaging_postbacks`.
</Step>
</Steps>

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

<Check>
You've manually configured your Messenger integration.
</Check>

</Tab>
<Tab title="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.

<Info>
You will need:

- A [published bot](/learn/get-started/quick-start)
- A [Facebook account](https://www.facebook.com/r.php?entry_point=login)
</Info>

1. In Botpress Studio, select **<Icon icon="boxes"/> 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.
</Tab>
</Tabs>

## Setting up the Messenger integration in Botpress

1. Go to the [Integration Hub](https://app.botpress.cloud/hub) in Botpress Cloud (if you don't have the integration installed yet).
2. Find and open the Messenger integration then click on the "Install to Bot" button, now go back to your bot settings.

The Messenger integration has the following settings:

* **Enabled**: Whether Botpress will communicate with Messenger
* **Webhook URL**: The URL for receiving data in Botpress
* **App ID**: The ID of your Meta App
* **App Secret**: The secret of your Meta App
* **Verify Token**: The token used to verify the webhook requests
* **Page ID**: The ID of your Facebook page
* **Access Token**: The access token used to send messages to the Messenger API
---

## Setting up Messenger
## Options

### Create a Facebook Page
The Messenger integration's **Configuration** menu offers a few additional options:

If you don't already have a Facebook page, you'll need to [create one](https://www.facebook.com/pages/create/). To link your bot to a preexisting page, you must have an administrator or developer role.
### Get user profile

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

Botpress can only interact with the version 15.0 or higher of the Messenger API. It isn't the default version in the app settings so it must be changed.
<Note>
This option is only available with [manual configuration](#manual-configuration).
</Note>

1. Go to your Meta app start page
2. In the left sidebar, expand the **Settings** menu and select **Advanced**
3. In the **Upgrade API version** section, select v15.0 or higher as the API version
4. Click on **Save changes**
### Download media

### Add Messenger Product
When enabled, this option automatically downloads media files using the [Files API](/api-reference/files-api/getting-started). When disabled, media files are displayed using their Messenger media URL.

Messenger isn't added by default in your Meta app, so it must be added manually
### Downloaded media expiry

1. In the left sidebar, click on **Add Product**
2. In the Facebook Messenger section click **Set Up**
Expiry time (in hours) for downloaded media files. An expiry time of 0 means the files will never expire. Defaults to 24 hours.

### App ID and Secret
---

1. In the left sidebar, expand the **Settings** menu and select **Basic**. Here you can find the App ID and App Secret
2. Click on the **Show** button in the **App Secret** text box. Copy the App ID and App Secret to your channel configuration
## Cards

### Verify Token
<Cards />

The verify token is used by Facebook to verify that you are the real owner of the provided webhook
---

You can generate any random alphanumerical string for this configuration. Paste it in your **Verify Token** channel configuration
## Tags

### Page ID and Access Token
You can read [event tags](/learn/guides/advanced/event-properties#param-tags) to get information about an active Messenger conversation:

1. In the left sidebar, expand the **Messenger** menu and select **Messenger API Settings**
2. In the **Access Tokens** section, click **Add or remove Pages** and add your Facebook page
3. Copy the number under your page name and paste it in your **Page ID** channel configuration
4. Click on **Generate token**. Copy this token and paste it in the **Access Token** channel configuration
### Message ID

### Save Configuration
To get the Messenger ID of a message:

Channel configuration is completed—you can now click **Save**. It's important to save your configuration in Botpress before updating the webhook in the Meta app settings; otherwise, Meta will be unable to validate the webhook URL.
```js
event.tags.message["messenger:id"]
```

## Webhook Configuration
### Recipient ID

To receive messages from Messenger in your Botpress bot, you will need to set up a webhook.
To get the Messenger ID of the recipient:

1. Go to your Meta app.
2. In the left sidebar, expand the **Messenger** menu and select **Messenger API Settings**
3. In the **Webhooks** section, click **Add Callback URL**
4. Copy paste the **Webhook URL** provided in the integration configuration page in Botpress.
5. Copy and paste the **Verify Token** that you generated earlier in the integration configuration page in Botpress.
6. Click on **Verify and save**. Make sure your channel configuration was saved before doing this step; otherwise, the webhook validation will fail
7. Click on **Add Subscriptions**, then select `messages` and `messaging_postbacks`. Then click **Save**.
```js
event.tags.message["messenger:recipientId"]
```

You may now start chatting with your bot on Messenger!
or

<Note>
Note
```js
event.tags.conversation["messenger:recipientId"]
```

If the bot doesn't answer to some people, that's probably because your app hasn't been reviewed by Meta yet (see [this section](/integrations/integration-guides/instagram#submit-your-app-for-meta-review)). But don't worry, this isn't mandatory to test your bot.
</Note>
### Sender ID

## Submit your App for Meta Review
To get the Messenger ID of the sender:

When your app is in Development Mode, your bot will work for admins, developers, and testers of the app only. After your app is approved and made public, it will work for the general public.
```js
event.tags.message["messenger:senderId"]
```

Read more about the App Review process on [the official documentation](https://developers.facebook.com/docs/app-review/submission-guide) and find some help if necessary [in this GitHub issue](https://github.com/microsoft/botframework-sdk/issues/1465).
or

You can find some troubleshooting [in this documentation](https://developers.facebook.com/docs/app-review/support/rejection-guides/messenger) in case you app get rejected.
```js
event.tags.conversation["messenger:senderId"]
```

## Send Greeting/Welcome Message
### Conversation ID

You can create a customized greeting from your Page that will appear in Facebook messages and in the Messenger app when someone begins a conversation with your Page for the first time. Your Page's greeting will appear before any messages are sent.
To get the Messenger ID of the conversation:

Read more about the [Messenger Greeting/Welcome Message](https://www.facebook.com/help/1698046970464236)
```js
event.tags.conversation["messenger:id"]
```

---
### User ID

## Cards
To get the Messenger ID of the user:

<Cards />
```js
event.tags.user["messenger:id"]
```