boomerang 0.6.0

An asynchronous Python library for building services on the Facebook Messenger Platform

Boomerang

Boomerang is an asynchronous Python library for building services on the Facebook Messenger Platform. See the documentation at ReadTheDocs!

Why should I use Boomerang?

• Requests are handled asynchronously, allowing for rapid handling of callbacks and messages. Boomerang is built on the incredibly fast Sanic webserver, uvloop replacement for asyncio’s event loop, and aiohttp for asynchronous HTTP requests.

• Boomerang has 100% test coverage and extensive documentation for learners.

• There are two options for interfacing with the Messenger Platform: use the high-level API which introduces abstractions like acknowledge, which marks a received message as seen and displays a ‘typing’ icon while preparing the actual response; or use the low-level API for more flexibility and send actions individually.

• The library is open-source under the MIT License, and can be used for commercial purposes.

Why shouldn’t I use Boomerang?

• The library uses Python 3.5’s async and await syntax, as does the underlying Sanic server. If support for older versions is required, Boomerang isn’t a great fit.

• Boomerang hosts its own server (Sanic), which allows for tightly-integrated and rapid handling. However, if you want to use a different server (like Flask), Boomerang isn’t suitable.

Example

The following example is a simple echo server. When a user sends a message to the bot, the bot echoes the message back:

from boomerang import Messenger, messages, events

# Set the app's API access tokens, provided by Facebook
VERIFY_TOKEN = 'your_webhook_token_here'
PAGE_TOKEN = 'your_page_access_token_here'

# Initialise the server
app = Messenger(VERIFY_TOKEN, PAGE_TOKEN)

@app.handle(events.MESSAGE_RECEIVED)
async def message_received(self, message):

    # Print the received message
    print('Received message from {0}'.format(message.user_id))
    print('> {0}'.format(message.text))

    # Inform the sender that their message is being processed
    await self.acknowledge(message)

    # Return the message's text to respond
    return message.text

app.run(hostname='0.0.0.0', debug=True)

Features

• Support for the Webhook, Send, Thread Settings, and User Profile APIs.

• Full support for message templates.

• High- or low-level interface for sending messages.

• Automatic attachment hosting: the library can send a local file by serving it statically with a unique URL, which is passed to Messenger. This is cached meaning files are only served once, helping performance.

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template. Cookiecutter is really cool and you should check it out!

History

0.6.0 (12-2-2017)

• BREAKING CHANGE: Handler functions are no longer overridden in the Messenger class; instead, the @app.handle decorator is used. See the documentation for more details.

• Handler functions can now simply return responses in a variety of formats, which are interpreted and sent as a reply.

0.5.0 (5-2-2017)

• Implement the User Profile API.

0.4.0 (5-2-2017)

• Implement the Thread Settings API.

0.3.0 (4-2-2017)

• Add automatic attachment hosting using the internal server

• Add proper handling of Messenger API errors

0.2.1 (1-2-2017)

• Update dependency versions to fix VersionConflict in Travis CI.

0.2.0 (1-2-2017)

• Implement the Send API. All non-beta templates and messages are supported (except for the airline templates).

0.1.0 (25-12-2016)

• Implement the Webhook API, with handling of all non-beta event types excepting the ‘message echo’ event, which will be added upon completion of the Send API implementation.

0.0.0 (22-12-2016)

• Initial development version.