Skip to main content

A Python Library For Using The Facebook Messenger Platform API

Project description

FBMQ (Facebook Messenger Platform Python Library)
=================================================

|PyPI| |Build Status| |Coverage Status| |PyPI|

A Python Library For Using The Facebook Messenger Platform API (Python
Facebook Chat & Chatbot Library) Facebook messenger platform api full
features are supported ## Table of Contents

- `Install <#install>`__
- `Handle webhook <#handle-webhook>`__
- `usage (with flask) <#usage-with-flask>`__
- `handlers <#handlers>`__
- `Send a message <#send-a-message>`__
- `basic <#basic>`__

- `text <#text>`__
- `image <#image>`__ / `audio <#audio>`__ / `video <#video>`__ /
`file <#file>`__
- `quick reply <#quick-reply>`__
- `quick reply callback <#quick-reply-callback>`__
- `typing on/off <#typing-onoff>`__

- `templates <#templates>`__

- `button <#template--button>`__
- `button callback <#button-callback>`__
- `generic <#template--generic>`__
- `receipt <#template--receipt>`__

- `options <#options>`__

- `notification type <#notification-type>`__
- `callback <#callback>`__

- `Example <#example>`__

Install
=======

::

pip install fbmq

Handle webhook
==============

how to handle messages from user to facebook page

Usage (with flask)
~~~~~~~~~~~~~~~~~~

.. code:: python

from flask import Flask, request
from fbmq import Page

page = fbmq.Page(PAGE_ACCESS_TOKEN)

@app.route('/webhook', methods=['POST'])
def webhook():
page.handle_webhook(request.get_data(as_text=True))
return "ok"

@page.handle_message
def message_handler(event):
sender_id = event['sender']['id']
message = event['message']

page.send(sender_id, "thank you! your message is '%s'" % message.get('text'))

@page.after_send
def after_send(payload, response):
print("complete")

handlers
~~~~~~~~

A spec in detail -
https://developers.facebook.com/docs/messenger-platform/webhook-reference

``@page.handle_message`` - This callback will occur when a message has
been sent to your page.

``@page.handle_echo`` - This callback will occur when a message has been
sent by your page

``@page.handle_delivery`` - This callback will occur when a message a
page has sent has been delivered.

``@page.handle_optin`` - This callback will occur when the
`Send-to-Messenger <https://developers.facebook.com/docs/messenger-platform/plugin-reference/send-to-messenger>`__
plugin has been tapped

``@page.handle_postback`` - Postbacks occur when a Postback button, Get
Started button, Persistent menu or Structured Message is tapped.

``@page.handle_read`` - This callback will occur when a message a page
has sent has been read by the user.

``@page.handle_account_linking`` - This callback will occur when the
Linked Account or Unlink Account call-to-action have been tapped.

``@page.after_send`` - This callback will occur when page.send function
has been called.

if you don't need a decorator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: python

page = fbmq.Page(PAGE_ACCESS_TOKEN, after_send=after_send)

@app.route('/webhook', methods=['POST'])
def webhook():
page.handle_webhook(request.get_data(as_text=True),
message=message_handler)
return "ok"

def message_handler(event):
sender_id = event['sender']['id']
message = event['message']

page.send(sender_id, "thank you! your message is '%s'" % message.get('text'))

def after_send(payload, response):
print("complete")

Send a message
==============

how to send a message from facebook page to user

Basic
~~~~~

Import
''''''

.. code:: python

from fbmq import Attachment, Template, QuickReply, Page

Text
''''

.. code:: python

page.send(recipient_id, "hello world!")

Image
'''''

jpg, png, gif support

.. code:: python

page.send(recipient_id, Attachment.Image(image_url))

Audio
'''''

.. code:: python

page.send(recipient_id, Attachment.Audio(audio_url))

Video
'''''

.. code:: python

page.send(recipient_id, Attachment.Video(video_url))

File
''''

.. code:: python

page.send(recipient_id, Attachment.File(file_url))

quick reply
'''''''''''

.. code:: python

quick_replies = [
QuickReply(title="Action", payload="PICK_ACTION"),
QuickReply(title="Comedy", payload="PICK_COMEDY")
]

# you can use a dict instead of a QuickReply class
#
# quick_replies = [{'title': 'Action', 'payload': 'PICK_ACTION'},
# {'title': 'Comedy', 'payload': 'PICK_COMEDY'}}


page.send(recipient_id,
"What's your favorite movie genre?",
quick_replies=quick_replies,
metadata="DEVELOPER_DEFINED_METADATA")

quick reply callback
''''''''''''''''''''

you can define easily a quick reply callback method.

.. code:: python

@page.callback_quick_reply(['PICK_ACTION', 'PICK_COMEDY'])
def callback_picked_genre(payload, event):
print(payload, event)

# Also supported regex, it works corretly
# @page.callback_quick_reply(['PICK_(.+)'])

typing on/off
'''''''''''''

.. code:: python

page.typing_on(recipient_id)
page.typing_off(recipient_id)

Templates
~~~~~~~~~

Template : Button
'''''''''''''''''

.. code:: python

buttons = [
Attachment.ButtonWeb("Open Web URL", "https://www.oculus.com/en-us/rift/"),
Attachment.ButtonPostBack("trigger Postback", "DEVELOPED_DEFINED_PAYLOAD"),
Attachment.ButtonPhoneNumber("Call Phone Number", "+16505551234")
]

# you can use a dict instead of a Button class
#
# buttons = [{'type': 'web_url', 'title': 'Open Web URL', 'value': 'https://www.oculus.com/en-us/rift/'},
# {'type': 'postback', 'title': 'trigger Postback', 'value': 'DEVELOPED_DEFINED_PAYLOAD'},
# {'type': 'phone_number', 'title': 'Call Phone Number', 'value': '+16505551234'}]

page.send(recipient_id, Template.Buttons("hello", buttons))

button callback
'''''''''''''''

you can define easily a button postback method (it works only postback
type buttons).

.. code:: python

@page.callback_button(['DEVELOPED_DEFINED_PAYLOAD'])
def callback_clicked_button(payload, event):
print(payload, event)

# Also supported regex, it works corretly
# @page.callback_button(['DEVELOPED_DEFINE(.+)'])

Template : Generic
''''''''''''''''''

.. code:: python

page.send(recipient_id, Template.Generic([
Template.GenericElement("rift",
subtitle="Next-generation virtual reality",
item_url="https://www.oculus.com/en-us/rift/",
image_url=CONFIG['SERVER_URL'] + "/assets/rift.png",
buttons=[
Template.ButtonWeb("Open Web URL", "https://www.oculus.com/en-us/rift/"),
Template.ButtonPostBack("tigger Postback", "DEVELOPED_DEFINED_PAYLOAD"),
Template.ButtonPhoneNumber("Call Phone Number", "+16505551234")
]),
Template.GenericElement("touch",
subtitle="Your Hands, Now in VR",
item_url="https://www.oculus.com/en-us/touch/",
image_url=CONFIG['SERVER_URL'] + "/assets/touch.png",
buttons=[
Template.ButtonWeb("Open Web URL", "https://www.oculus.com/en-us/rift/"),
Template.ButtonPostBack("tigger Postback", "DEVELOPED_DEFINED_PAYLOAD"),
Template.ButtonPhoneNumber("Call Phone Number", "+16505551234")
])
]))

Template : Receipt
''''''''''''''''''

.. code:: python

element = Template.ReceiptElement(title="Oculus Rift",
subtitle="Includes: headset, sensor, remote",
quantity=1,
price=599.00,
currency="USD",
image_url=CONFIG['SERVER_URL'] + "/assets/riftsq.png"
)

address = Template.ReceiptAddress(street_1="1 Hacker Way",
street_2="",
city="Menlo Park",
postal_code="94025",
state="CA",
country="US")

summary = Template.ReceiptSummary(subtotal=698.99,
shipping_cost=20.00,
total_tax=57.67,
total_cost=626.66)

adjustment = Template.ReceiptAdjustment(name="New Customer Discount", amount=-50)

page.send(recipient_id, Template.Receipt(recipient_name='Peter Chang',
order_number='1234',
currency='USD',
payment_method='Visa 1234',
timestamp="1428444852",
elements=[element],
address=address,
summary=summary,
adjustments=[adjustment]))

Options
~~~~~~~

notification type
'''''''''''''''''

support notification\_type as a option

``NotificationType.REGULAR (default)``,
``NotificationType.SILENT_PUSH``, ``NotificationType.NO_PUSH``

::

page.send(recipient_id, 'hello', notification_type=NotificationType.NO_PUSH)

callback
''''''''

you can set a callback function to each ``page.send``

::

def callback(payload, response):
print('response : ' + response.text)

page.send(recipient_id, 'hello', callback=callback)

Example
=======

1. fill example/config.py
2. run server

.. code:: bash

cd example
virtualenv env
source env/bin/activate
pip install -r requirements.txt
python server.py

|image4| |image5| |image6| |image7| |image8| |image9| |image10|
|image11| |image12|

.. |PyPI| image:: https://img.shields.io/pypi/v/fbmq.svg?v=1&maxAge=3601
:target: https://pypi.python.org/pypi/fbmq
.. |Build Status| image:: https://travis-ci.org/conbus/fbmq.svg?branch=master&v=1
:target: https://travis-ci.org/conbus/fbmq
.. |Coverage Status| image:: https://coveralls.io/repos/github/conbus/fbmq/badge.svg?branch=master
:target: https://coveralls.io/github/conbus/fbmq?branch=master
.. |PyPI| image:: https://img.shields.io/pypi/l/fbmq.svg?v=1&maxAge=2592000
:target: https://pypi.python.org/pypi/fbmq
.. |image4| image:: ./example/assets/screen2.jpg
.. |image5| image:: ./example/assets/screen3.jpg
.. |image6| image:: ./example/assets/screen4.jpg
.. |image7| image:: ./example/assets/screen5.jpg
.. |image8| image:: ./example/assets/screen6.jpg
.. |image9| image:: ./example/assets/screen7.jpg
.. |image10| image:: ./example/assets/screen8.jpg
.. |image11| image:: ./example/assets/screen9.jpg
.. |image12| image:: ./example/assets/screen10.jpg

Project details


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
fbmq-2.0.0b1.tar.gz (7.7 kB) Copy SHA256 hash SHA256 Source None Aug 26, 2016

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page