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>`__
- `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)
handlers
~~~~~~~~
``@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.
if you don't need a decorator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
@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)
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)
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)
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)
fbpage.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]))
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
=================================================
|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>`__
- `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)
handlers
~~~~~~~~
``@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.
if you don't need a decorator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
@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)
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)
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)
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)
fbpage.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]))
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
fbmq-1.5.3.tar.gz
(6.7 kB
view hashes)