Install & Compatibility
Where this runs
tested against v6.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 21.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.1s · import 0.000s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BaseMessenger
✓ from fbmessenger import BaseMessenger
✗ from fbmessenger import BaseMessenger
This Flask example demonstrates how to set up a basic webhook for the Facebook Messenger API using fbmessenger. It listens for incoming messages, verifies the webhook, and echoes back received text messages. Ensure you have Flask installed (`pip install Flask`) and configured environment variables for `FB_PAGE_TOKEN`, `FB_VERIFY_TOKEN`, and optionally `FB_APP_SECRET` based on your Facebook App setup.
import os
from flask import Flask, request
from fbmessenger import BaseMessenger, MessengerClient
app = Flask(__name__)
app.debug = True
# Extend BaseMessenger and implement webhook handlers
class Messenger(BaseMessenger):
def __init__(self, page_access_token, app_secret=None):
self.page_access_token = page_access_token
self.app_secret = app_secret
self.client = MessengerClient(self.page_access_token, app_secret=self.app_secret)
def message(self, message):
# Handle incoming text messages
if 'text' in message['message']:
received_text = message['message']['text']
sender_id = message['sender']['id']
self.client.send({'text': f'Received: {received_text}'}, 'RESPONSE', recipient_id=sender_id)
def delivery(self, message):
pass # Handle message delivery confirmations
def read(self, message):
pass # Handle message read confirmations
def account_linking(self, message):
pass # Handle account linking events
def postback(self, message):
pass # Handle postback events
def optin(self, message):
pass # Handle opt-in events
# Initialize Messenger with tokens from environment variables
messenger = Messenger(
os.environ.get('FB_PAGE_TOKEN', ''),
app_secret=os.environ.get('FB_APP_SECRET', '')
)
@app.route('/webhook', methods=['GET', 'POST'])
def webhook():
if request.method == 'GET':
# Webhook verification
if request.args.get('hub.verify_token') == os.environ.get('FB_VERIFY_TOKEN'):
return request.args.get('hub.challenge')
raise ValueError('FB_VERIFY_TOKEN does not match.')
elif request.method == 'POST':
# Handle incoming messages
messenger.handle(request.get_json(force=True))
return ''
if __name__ == '__main__':
# Remember to set FB_PAGE_TOKEN, FB_VERIFY_TOKEN, and FB_APP_SECRET (optional) environment variables.
# Example: export FB_PAGE_TOKEN='your_page_access_token'
# export FB_VERIFY_TOKEN='your_verify_token_string'
# export FB_APP_SECRET='your_app_secret' (if enabled)
app.run(host='0.0.0.0', port=5000)
Debug
Known issues
breakingVersion 6.0.0 introduced a breaking change by switching the input parameter from 'message' to 'recipient_id' for methods like send().fixUpdate your method calls to pass 'recipient_id' explicitly instead of 'message' object for identifying the recipient.
affects: 6.0.0 and above
gotchaFacebook Page-Scoped IDs (PSIDs) must be used when interacting with the Messenger API. These are unique to your page and differ from global Facebook user IDs or app-scoped IDs from other integrations. Using incorrect IDs will result in failed API calls.fixEnsure that the user IDs you receive from Messenger webhooks are stored and used as `recipient_id` for outgoing messages.
affects: All versions
gotchaThe Facebook Messenger API frequently updates, sometimes introducing changes to message types, permissions, or security features (e.g., end-to-end encryption by default). While fbmessenger aims to abstract this, underlying API changes can affect compatibility or require updates to your bot's logic.fixRegularly consult the official Meta Messenger Platform documentation for any breaking changes or new requirements. This library might not receive updates to match every new API version.
affects: All versions, due to external API changes
Upgrade
Version history
6.0.0latest on PyPI · released Apr 24, 2019
Audit
Dependencies
requestsrequiredUsed internally for making HTTP requests to the Facebook Messenger API.