Docs

Messenger and Facebook

Add your bot to Messenger and Facebook using the official integration

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

Setup

    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.

    For advanced use cases, you can use your own Meta app with our integration.

    Get your Meta app ready

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

    Add the Messenger API

    To configure your integration, you need to access the Messenger API:

    1. Log in to your Meta developer account.
    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.

    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.

    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, you can set up the integration in Botpress:

    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.

    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:

    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.

    Client Secret (Optional)

    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.

    Verify Token

    Used by Meta to verify that you’re the real owner of the provided webhook. Can be any alphanumeric string.

    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.

    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:

    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

    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.

    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.

    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.

    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.

    Download media

    When enabled, this option automatically downloads media files using the Files API. 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.

    In Botpress Studio, enter your Main Workflow.

    Add a new Node to the Workflow.

    Rename the Node to Router, then move it between the Start Node and any other existing Nodes:

    Reply to comments in DMs 1

    Add two Expression Cards to the Router Node.

    Open the second Expression Card’s inspector. Next to the Condition field, toggle to disable generative AI.

    Configure this Card for conversations started normally:

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

    Open the first Expression Card’s inspector. Next to the Condition field, toggle to disable generative AI.

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

    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

    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.

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

    Add a Text Card to the new Node.

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

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

    Reply to comments in DMs 3

    Step 3: Start a DM conversation from the comment

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

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

    Add the Start DM Conversation from Comment Card to the new Node.

    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.

    Attach the Reply_to_comment Node to the DM_reply Node. Then, attach the DM_reply Node to the End Node:

    Reply to comments in DMs 4

    Cards

    Get or Create a Conversation

    Proactively create a conversation from a bot

    inputobject
    outputobject

    Get or Create a User

    Proactively create a user from a bot

    inputobject
    outputobject

    Start DM Conversation from Comment

    Start a DM conversation from a comment

    inputobject

    startTypingIndicator

    inputobject

    stopTypingIndicator

    inputobject

    Triggers

    Tags

    You can read event tags to get information about an active Messenger conversation:

    Message ID

    To get the Messenger ID of a message:

    event.tags.message['messenger:id']

    Recipient ID

    To get the Messenger ID of the recipient:

    event.tags.message['messenger:recipientId']

    Sender ID

    To get the Messenger ID of the sender:

    event.tags.message['messenger:senderId']

    Conversation ID

    To get the Messenger ID of the conversation:

    event.tags.conversation['messenger:id']

    User ID

    To get the Messenger ID of the user:

    event.tags.user['messenger:id']