FBBOTW: A Facebook Messenger Platform API Wrapper

Build Status Documentation Status PyPI MIT licensed

This wrapper makes it simpler to user the Facebook Messenger platform wrapping the endpoints as functions.

For exemple, to send a text message to the user you can easily do:

from fbbotw import fbbotw
# ...

user_fbid = "<user fb id>"
my_message = "Hello World"

fbbotw.post_text_message(fbid=user_fbid, message=my_message)
# The user with the specified fbid will receive the text 'Hello World'

This is much less code than the traditional way to call the Send API and send a text. Using requests and json you probably would do like this:

fbid = "<user psid>"
message = "Hello World"
url = 'https://graph.facebook.com/v2.6/me/messages?access_token={0}'
url = url.format(PAGE_ACCESS_TOKEN)
header = {"Content-Type": "application/json"}
payload = {}
payload['recipient'] = {'id': fbid}
payload['message'] = {'text': message}
data = json.dumps(payload)
response = requests.post(url=url, headers=header, data=data)

Get Started

1- Install

pip install fbbotw

2 - Configure it

The only configuration needed is to set the PAGE_ACCESS_TOKEN with the value you got from the facebook app dashboard. If you are using Django, create the variable in your settings.py. If not, define the variable in your enviroment:

2.1 - Django

In your settings.py define the variable PAGE_ACCESS_TOKEN that was generated on the app configuration from facebook.

#settings.py
PAGE_ACCESS_TOKEN = "<your access token>"

2.2 - Not Django

Create an os environment variable called PAGE_ACCESS_TOKEN:

export PAGE_ACCESS_TOKEN='<your access token>'

3 - Import and Use it

After setting the access token, just import and use fbbotw methods:

from fbbotw import fbbotw

fbbotw.post_sender_action(fbid="<user psid>", sender_action="typing_on")

See the next topic to learn about the methods provided by the package

The Response Return

This package uses the Requests library to consume the Messenger API. For that reason, almost every function of this package, except get_user_information, returns an Response object

The Response object represent the server response to an HTTP request. In our case, the facebook response to our request.

# Response object represents what the facebook server answered
response = fbbotw.post_text_message(fbid="1223", message="Hi user")
# The response objects has some attributes and methods to help verify the response:
if (response.status_code == 200):
    # if response code is 200, request was successful
    # We can see the response body calling the method .json()
    print(response.json())
    # will print {'message_id': 'mid.$cAAJoUiFKdHJi-Oj9r1cx6O1cpi6C', 'recipient_id': '1223'}
    # message_id: id of sent message
    # recipient_id: fbid of user that got the message

This topic on the Request docs describes all the Response attributes and methods.

Debugging

fbbotw doesn’t do any verification on the parameters and all validation is done on the facebook server. If one method isn’t working, check the response object returned. It will describe which was the error or bad parameter. You can check that by calling the .json() method on the response object.

Current wrapper covering for the Messenger Platform 2.2

  • [ ] Send API
  • [x] Content Types
  • [ ] Miscellaneous
  • [ ] Plugin Reference
  • [ ] Messenger Code API
  • [ ] Messaging Insights API