Messenger integration enables your ChatBotKit bots to interact with users on Facebook Messenger, one of the world's most popular messaging platforms with over 1 billion active users. This integration provides real-time message handling, webhook-based event processing, and comprehensive support for attachments, postbacks, and persistent menus.

The integration handles all aspects of Facebook Messenger's API, including webhook verification, message sending and receiving, conversation session management, and seamless handoff to human agents when needed. Your bot can respond to text messages, process image attachments, handle button clicks and quick replies, and maintain conversation context across multiple interactions.

Creating Messenger Integrations

Creating a Messenger integration is the first step to deploying your bot on Facebook Messenger. The integration requires a Facebook Page and an access token from the Facebook Developer Portal with appropriate permissions to send and receive messages on behalf of your page.

Before creating the integration in ChatBotKit, you need to set up a Facebook App in the Facebook Developer Portal, add the Messenger product, and generate a Page Access Token with the following permissions: pages_messaging, pages_manage_metadata, and pages_read_engagement. This token authenticates your integration and allows ChatBotKit to send messages through your Facebook Page.

The integration creation process generates a unique verify token that you'll use to configure the webhook in Facebook's Developer Portal. This verify token ensures that only Facebook can send webhook events to your integration, preventing unauthorized access and maintaining security.

POST /api/v1/integration/messenger/create
Content-Type: application/json

{
  "name": "Customer Support Messenger Bot",
  "description": "Automated customer support on Messenger",
  "botId": "bot_abc123",
  "accessToken": "EAAxxxxxxxxxxxxxx",
  "sessionDuration": 86400000,
  "attachments": true,
  "contactCollection": true
}
http

The accessToken parameter is your Facebook Page Access Token, which you can generate in the Facebook Developer Portal. The sessionDuration parameter controls how long conversation sessions persist (in milliseconds), with a default of 24 hours. Setting attachments to true enables your bot to receive and process image, video, and file attachments sent by users.

Important: After creating the integration, you must complete the webhook setup in Facebook's Developer Portal using the callback URL and verify token provided by ChatBotKit. Without proper webhook configuration, your integration will not receive messages from Facebook Messenger. Additionally, you should call the setup endpoint to configure the persistent menu and get started button for an optimal user experience.

Security Note: Store your access token securely and never expose it in client-side code. The access token grants full control over your Facebook Page's messaging capabilities and should be treated as a sensitive credential. Consider using short-lived tokens and rotating them periodically for enhanced security.

Webhook Event Handling and Verification

The callback endpoint serves as the webhook receiver for Facebook Messenger events, handling both the initial webhook verification process required by Facebook and the ongoing stream of message events sent whenever users interact with your bot. This endpoint is the bridge between Facebook's Messenger platform and ChatBotKit's conversation processing system, ensuring reliable, real-time message delivery and bot response handling.

Facebook's webhook system requires a two-step verification process before sending live events. First, Facebook sends a GET request to your callback URL with verification parameters including hub.mode set to "subscribe", hub.verify_token containing the token you provided during webhook setup, and hub.challenge containing a random string that must be returned exactly as received to complete verification. ChatBotKit automatically handles this verification by comparing the provided token with your integration's verify token and returning the challenge response when they match.

Once verified, Facebook begins sending POST requests containing message events, postback events, and other user interactions. Each webhook payload contains an array of entry objects, with each entry containing a messaging array that holds individual user interactions. The callback endpoint processes these events by queuing them for asynchronous processing, ensuring fast response times and preventing webhook timeouts even when handling complex bot logic or external API calls.

The callback URL you configure in Facebook's Developer Portal must match this endpoint exactly. The URL format is:

https://api.chatbotkit.com/api/v1/integration/messenger/{messengerIntegrationId}/callback

Replace {messengerIntegrationId} with your actual integration ID from ChatBotKit. This URL must be publicly accessible and support both GET (for verification) and POST (for events) requests. Facebook requires HTTPS with a valid SSL certificate and will reject webhooks using self-signed certificates or plain HTTP connections.

Webhook Configuration Steps:

1. Navigate to your Facebook App in the Developer Portal
2. Select Messenger from the products list
3. Click "Setup Webhooks" in the Webhooks section
4. Enter your callback URL with the integration ID
5. Enter the verify token from your integration's fetch response
6. Subscribe to webhook events: messages, messaging_postbacks, and optionally message_deliveries and message_reads
7. Click "Verify and Save" to complete the webhook configuration

Event Processing: The callback endpoint immediately acknowledges webhook deliveries with a 200 OK response to prevent Facebook from marking deliveries as failed and implementing exponential backoff. Events are then queued for asynchronous processing, where conversation engines handle message routing, bot response generation, session management, and context tracking. This architecture ensures webhook responses stay within Facebook's strict timeout requirements while allowing complex bot logic to execute without constraints.

Deleting Messenger Integrations

Deleting a Messenger integration permanently removes the connection between ChatBotKit and your Facebook Messenger page, stopping all message processing and webhook event handling. This operation is irreversible and should be performed carefully, as it immediately terminates all active conversations and prevents the bot from responding to new messages.

Before deleting an integration, consider the impact on active users who may be in the middle of conversations. All session data and conversation context is preserved in ChatBotKit's conversation history for analytics and review purposes, but the bot will no longer respond to messages sent through the Facebook Messenger channel. Users attempting to interact with your page after deletion will receive no automated responses until you create a new integration or enable manual responses through Facebook's Page Inbox.

After deletion, you should also remove the webhook configuration from Facebook's Developer Portal to prevent unnecessary webhook delivery attempts and error logging. Navigate to your app's Messenger settings, locate the webhooks section, and either remove the webhook subscription or update it to point to a different endpoint if you're migrating to a new integration.

POST /api/v1/integration/messenger/{messengerIntegrationId}/delete
Content-Type: application/json

{}
http

The deletion process is immediate and cannot be undone. If you need to temporarily disable the integration without losing configuration, consider removing the webhook subscription in Facebook's Developer Portal instead, which stops message delivery while preserving your ChatBotKit integration settings for future reactivation.

Data Retention: Deleting the integration does not delete historical conversation data, contact information collected through the integration, or analytics data. These records remain accessible in ChatBotKit for reporting and compliance purposes. If you need to delete user data, use the conversation and contact deletion endpoints separately.

Best Practice: Before deletion, export any important analytics data, review active conversation logs, and notify users if the bot will no longer be available. Consider maintaining a backup integration for testing or development purposes to avoid disrupting production services.

Fetching Messenger Integration Details

Retrieving the full details of a specific Messenger integration provides access to all configuration settings, connection parameters, and metadata associated with that integration. This is essential for reviewing current settings, troubleshooting connection issues, and gathering information needed for webhook configuration in Facebook's Developer Portal.

When you fetch an integration, you receive comprehensive information including the integration's name, description, associated bot and blueprint IDs, the webhook verify token required for Facebook webhook setup, session duration settings, and feature flags such as attachment support and contact collection. This detailed view enables you to verify your configuration matches your requirements before deploying to production.

The verify token included in the response is crucial for completing the webhook setup process in Facebook's Developer Portal. You'll need to copy this exact token and paste it into the webhook verification field to establish the secure connection between Facebook Messenger and ChatBotKit. The token ensures that only authorized webhooks can send events to your integration.

GET /api/v1/integration/messenger/{messengerIntegrationId}/fetch
http

Security Considerations

For security reasons, the accessToken field is returned as a sentinel value instead of the actual credential:

• Returns "********" if an access token is configured
• Returns null if no access token has been set

This allows you to verify that credentials are configured without exposing the actual token values. When updating an integration, you can send back the sentinel value "********" and the existing token will be preserved unchanged. Only send a new actual token value if you want to update it.

Use Case: Fetch integration details when you need to verify the webhook callback URL for Facebook, confirm which bot is connected to the integration, review session timeout settings, or check whether attachment processing is enabled. This endpoint is also useful for programmatically auditing your integration configurations across multiple deployments.

Setting Up Messenger Integration Features

The setup endpoint configures essential Messenger features that enhance user experience and provide seamless conversation management capabilities. This includes setting up the Get Started button that greets new users when they first interact with your page, and configuring the persistent menu that gives users access to important actions like requesting human agent assistance.

Calling this endpoint is a crucial step after creating your Messenger integration and configuring the webhook in Facebook's Developer Portal. The setup process uses your Facebook Page Access Token to communicate with Facebook's Graph API and establish the conversation interface elements that users will interact with. Without this setup, users may experience a basic, unenhanced chat interface without guided entry points or quick action options.

The Get Started button appears when a user first opens a conversation with your page, providing a welcoming entry point and sending a standardized payload that your bot can use to initiate an onboarding flow or greeting sequence. The persistent menu appears as a hamburger icon in the composer area, offering users quick access to predefined actions such as transferring to a human agent, restarting the conversation, or accessing help resources.

POST /api/v1/integration/messenger/{messengerIntegrationId}/setup
Content-Type: application/json

{}
http

Updating Messenger Integrations

Updating a Messenger integration allows you to modify configuration settings, change the connected bot, rotate access tokens, adjust session durations, or enable and disable features like attachment processing. This flexibility ensures your integration can evolve as your requirements change without needing to recreate the entire integration and reconfigure webhooks.

Common update scenarios include switching to a different bot implementation after testing and refinement, rotating Facebook Page Access Tokens for security compliance, adjusting session timeout values based on user behavior patterns, and enabling new features like attachment support after initial deployment. Updates take effect immediately for new conversations, while existing active conversations continue using their original configuration until the session expires.

When updating the access token, ensure the new token has the same permissions as the original token (pages_messaging, pages_manage_metadata, and pages_read_engagement). Token rotation is recommended every 60 days as a security best practice. If you change the access token, you do not need to reconfigure the webhook in Facebook's Developer Portal, as the webhook verification uses the verify token which remains constant.

POST /api/v1/integration/messenger/{messengerIntegrationId}/update
Content-Type: application/json

{
  "name": "Updated Customer Support Bot",
  "description": "Enhanced with new capabilities",
  "botId": "bot_xyz789",
  "sessionDuration": 172800000,
  "attachments": true,
  "contactCollection": true
}
http

The update operation supports partial updates, meaning you only need to include the fields you want to change. Omitted fields retain their current values. This allows you to make targeted adjustments without needing to resend the entire configuration.

Important: Changing the bot ID immediately affects all new conversations but does not interrupt active conversations. Users with ongoing sessions will continue interacting with the previous bot until their session expires or they start a new conversation. Plan bot updates during low-traffic periods or use staged rollouts for critical changes.

Metadata Updates: The metadata field supports custom tags and properties that can be used for organization, analytics, and filtering. Updates to metadata are merged with existing values rather than replacing them entirely, allowing you to add or modify specific properties without affecting others.

Listing Messenger Integrations

Retrieving a list of your Messenger integrations allows you to view all configured bots connected to Facebook Messenger, review their settings, and manage multiple integrations from a centralized location. This is particularly useful when managing multiple Facebook Pages or deploying different bots for various use cases.

The list endpoint supports pagination through cursor-based navigation, enabling efficient retrieval of large numbers of integrations. You can control the order of results (ascending or descending by creation date) and limit the number of items returned per request to optimize performance and reduce unnecessary data transfer.

Each integration in the list includes essential information such as the integration name, description, associated bot ID, webhook verify token, session duration settings, and attachment support configuration.

Security Considerations

For security reasons, the accessToken field is returned as a sentinel value:

• Returns "********" if an access token is configured
• Returns null if no access token has been set

This allows you to verify which integrations have credentials configured without exposing the actual secret values.

GET /api/v1/integration/messenger/list?order=desc&take=10
http

The response includes an array of integration objects with their configuration details. You can filter results by blueprint ID to find integrations associated with specific blueprints, or use metadata filters to locate integrations based on custom tags and properties.

Pagination: Use the cursor parameter to navigate through pages of results. The initial request returns the first page along with a cursor for the next page. Include this cursor in subsequent requests to retrieve additional pages until no more results are available.

Best Practice: When managing multiple integrations, use descriptive names and consistent metadata to make it easier to identify and organize your Messenger bots. This becomes especially important as your deployment grows to include multiple pages, languages, or customer segments.