fbmessenger

fbmessenger is a Python client for the Facebook Messenger Platform API. It wraps the Graph API’s messaging endpoints in a MessengerClient class and provides a BaseMessenger abstract base class that developers subclass to route incoming webhook events (messages, postbacks, delivery/read receipts, optins, account linking) to their own handler methods.

Beyond raw message sending, the library ships typed helpers for the richer parts of the Send API surface: generic, button, receipt, and media templates, quick replies, structured attachments (image/audio/video/file), sender actions like typing indicators, and Messenger Profile configuration (greeting text, get-started button, persistent menu, whitelisted domains). It has been a long-running dependency for Python-based Messenger bots, most commonly paired with Flask or Django webhook views.

What You Get

• A MessengerClient class covering the Send API, sender actions, Messenger Profile, attachment upload, and account (un)linking endpoints
• A BaseMessenger abstract base class that dispatches incoming webhook payloads to message, postback, delivery, read, optin, and account_linking handler methods you implement
• Element and template classes (Text, Button, Element, GenericTemplate, ButtonTemplate, ReceiptTemplate, MediaTemplate) that serialize to the exact JSON shapes the Send API expects via to_dict()
• Attachment classes for images, audio, video, and files, plus a dedicated upload_attachment call for Facebook’s reusable attachment IDs
• Quick reply and thread-settings (greeting text, get-started button, persistent menu, domain whitelisting) helpers for configuring a bot’s Messenger Profile
• Built-in appsecret_proof generation (HMAC-SHA256) for securing Graph API requests when an app secret is configured

Common Use Cases

• Implementing a Flask or Django webhook view that verifies Facebook’s challenge token and routes POSTed events through BaseMessenger.handle()
• Sending structured messages back to users — receipts, carousels, button prompts, quick-reply menus — without manually building Graph API JSON
• Configuring a bot’s persistent menu, greeting text, and get-started button once at setup time via the Messenger Profile API
• Uploading and reusing media attachments across multiple conversations instead of re-uploading the same image or file each time
• Adding appsecret_proof to Graph API calls to satisfy Facebook’s stricter app-secret verification requirements

Under The Hood

Architecture The library is organized as a thin, single-purpose wrapper: MessengerClient in fbmessenger/__init__.py owns every outbound HTTP call to the Graph API (send, send_action, set_messenger_profile, upload_attachment, account linking, and domain whitelisting), while BaseMessenger is an abstract base class that composes a MessengerClient instance and exposes abc.abstractmethod-declared handlers (message, postback, delivery, read, optin, account_linking) that handle() dispatches to based on which key is present in each incoming webhook entry. Supporting modules (elements.py, templates.py, attachments.py, quick_replies.py, thread_settings.py, sender_actions.py) are plain data classes whose only job is a to_dict() method that serializes to the Graph API’s expected JSON shape, so the request-building layer and the payload-modeling layer stay cleanly separated. There is no framework coupling — consumers plug BaseMessenger into whatever web framework’s routing they use.

Tech Stack Pure Python with a minimal runtime footprint: requests for HTTP, six for Python 2/3 compatibility, and the standard library’s hmac/hashlib for appsecret-proof generation. setup.py targets Python 2.7 and 3.3+ classifiers, reflecting its 2016 origin, and pins no upper bounds on requests. No async support, no bundled web framework — the README’s example wiring is Flask, but the library itself is framework-agnostic.

Code Quality Test coverage is extensive relative to the library’s size — a tests/ directory with one file per module (test_client.py, test_elements.py, test_templates.py, test_attachments.py, test_thread_settings.py, test_quick_replies.py, test_sender_actions.py, test_messenger.py) totaling roughly 3,200 lines against ~1,100 lines of library code, using pytest with responses for HTTP mocking and coverage/pytest-cov for reporting. CI runs via Travis. Naming and structure are consistent across modules, though there is no static type checking (no type hints, no mypy) and no linter enforcement wired into CI beyond what flake8/pylint are listed for in requirements.txt.

What Makes It Unique Its value is coverage breadth rather than novel technique: it models nearly the entire Messenger Send API surface — every template type, attachment kind, quick reply, and Messenger Profile setting — as typed Python classes with to_dict() serialization, so bot authors get one abstraction (BaseMessenger.handle()) that stays stable across API surface expansions. It predates and is unrelated to Meta’s official Business SDK, filling the gap for Python developers who wanted a lightweight, framework-agnostic client rather than a full multi-product SDK.