Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Facebook messenger bot framework

Project Description


koslab.messengerbot makes writing Facebook Messenger Bot easier by providing a framework that handles and abstract the Bots API. It is originally developed using Morepath as the web request processor and the default hub implementation is on morepath, but this library should work with any Python web frameworks

Example: Writing An Echo Bot

Lets install koslab.messengerbot

pip install koslab.messengerbot

Now lets write our EchoBot in

from import BaseMessengerBot

# bot implementation
class EchoBot(BaseMessengerBot):

   GREETING_TEXT = 'Hello!. EchoBot, at your service!'
   STARTUP_MESSAGE = {'text': 'Hi!, lets get started!' }

   def message_hook(self, event):
       text = event['message'].get('text', '')
       self.send(recipient=event['sender'], message={'text': text})

And now lets write a hub config file, config.yml.

webhook: webhook
use_message_queue: false
message_queue: amqp://guest:guest@localhost:5672//
hub_verify_token: <MY-VERIFY-TOKEN>
  - page_id: <PAGE-ID>
    title: EchoBot
    class: echobot:EchoBot
    access_token: <PAGE-ACCESS-TOKEN>

Start the bot

messengerbot_hub config.yml

Finally proceed to follow the Messenger Platform Getting Started guide to get your bot configured and registered in Facebook.

Bot Configuration


Dictionary mapping of payload to name of object method that will handle the payload. Default value is:



   'mypostback': 'mypostback_hook'

def mypostback_hook(self, event):

Greeting text for new threads. Default value is:

GREETING_TEXT = 'Hello World!'

Message object to be sent when Get Started menu is clicked. Default value is:

STARTUP_MESSAGE = { 'text' : 'Hello World!' }

Persistent menu call_for_action buttons configuration. Default value is:

   'type': 'postback',
   'title': 'Get Started',
   'payload': 'messengerbot.get_started'

Bot Hooks

Following are the list of hooks that can be implemented on the bot

Handles Message Received and Message Echo event.
Handles Postback Received event. This hook have a default implementation which triggers methods based on payload value. To define the mapping, configure POSTBACK_HANDLERS class variable.
Handles Authentication event.
Handles Account Linking event.
Handles Message Delivered event.
Handles Message Read event

Send API

BaseMessengerBot class provide a send method to send responses to Facebook Messenger Bot service. Parameters are:

Recipient object. Eg: { 'id': '12345678'}
Message object. Refer to Facebook Send API reference for supported messages
Sender actions. Supported values: mark_seen, typing_on, typing_off

Note: If message is defined, sender_action value will be ignored.

A convenience method reply can also be used to send a response. Parameters are:

Event object
Accepts string, callable or message object. Strings are automatically converted into message object. Callable will be called with the event object as its parameter.

Postback Payload

Postback values may be a JSON object or a string. In the case of Postback in JSON object format, an event key is required for routing postbacks to the right handler by postback_hook. For string postback values, the whole string is treated as the event key.


Session Management is provided through a thin wrapper around Beaker Cache. Current conversation session variable may be acquired through get_session method on BaseMessengerBot class. Session object is dict-like and may be treated as such.

def message_hook(self, event):
    session = self.get_session(event)

Messenger Bot with AMQP

AMQP queuing is supported by the hub process. To use this, in config.yml simply set use_message_queue to true and configure the transport uri to the message queue on message_queue setting. The queue is implemented using Kombu, so you may also use other transports that are supported by Kombu

use_message_queue: true
message_queue: amqp://guest:guest@localhost:5672//

Conversation API

NOTE: This is a draft spec. Not yet implemented. Inputs are welcomed.


conversation: myconversation
   - message: What is your name?
     type: text
     store: name
   - message: Please share your photo
     type: image-attachment
     store: photo
   - message: Please share your location
     type: location-attachment
     store: location
   - message:
       - type: generic-template
            - title: Summary
              subtitle: Summary
              image_url: ${data['photo']['url']}
                  - type: postback
                    title: Save


Note: place names and roles of the people who contribute to this package
in this file, one to a line, like so:
  • Mohd Izhar Firdaus Bin Ismail, Original Author


1.0b5 (2016-08-09)

  • Rearrange priority of event handlers so that quick reply postbacks are caught [Izhar Firdaus]

1.0b4 (2016-08-08)

  • Ignore CLI when starting up hub [Izhar Firdaus]

1.0b3 (2016-08-08)

  • Ensure that all child processes are killed when parent is terminated. [Izhar Firdaus]

1.0b2 (2016-07-13)

  • Bug with page_id mapping. Ensure it is read as string now instead of integer [Izhar Firdaus]

1.0b1 (2016-07-13)

  • Initial fully functional bot framework with hub implementation [Izhar Firdaus]

Release History

This version
History Node


History Node


History Node


History Node


History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(11.3 kB) Copy SHA256 Hash SHA256
Source None Aug 9, 2016

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Google Google Cloud Servers