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
Lets install koslab.messengerbot
pip install koslab.messengerbot
Now lets write our EchoBot in echobot.py
from koslab.messengerbot.bot 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>
bots:
- 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.
POSTBACK_HANDLERS
Dictionary mapping of payload to name of object method that will handle the payload. Default value is:
POSTBACK_HANDLERS = {}
Example:
POSTBACK_HANDLERS = { 'mypostback': 'mypostback_hook' } def mypostback_hook(self, event): ...
GREETING_TEXT
Greeting text for new threads. Default value is:
GREETING_TEXT = 'Hello World!'
STARTUP_MESSAGE
Message object to be sent when Get Started menu is clicked. Default value is:
STARTUP_MESSAGE = { 'text' : 'Hello World!' }
PERSISTENT_MENU
Persistent menu
call_for_action
buttons configuration. Default value is:PERSISTENT_MENU = [{ 'type': 'postback', 'title': 'Get Started', 'payload': 'messengerbot.get_started' }]
Following are the list of hooks that can be implemented on the bot
message_hook
Handles Message Received and Message Echo event.
postback_hook
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.authentication_hook
Handles Authentication event.
account_linking_hook
Handles Account Linking event.
message_delivered_hook
Handles Message Delivered event.
message_read_hook
Handles Message Read event
BaseMessengerBot
class provide a send
method to send responses to Facebook Messenger Bot service. Parameters are:
recipient
Recipient object. Eg:
{ 'id': '12345678'}
message
Message object. Refer to Facebook Send API reference for supported messages
sender_action
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
Event object
message
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 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)
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//
NOTE: This is a draft spec. Not yet implemented. Inputs are welcomed.
Spec
conversation: myconversation
steps:
- 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
elements:
- title: Summary
subtitle: Summary
image_url: ${data['photo']['url']}
buttons:
- type: postback
title: Save
payload: myconversation.save