Facebook Messaging API SDK for Python
Project description
python-messengerbot-sdk
===================
SDK of the Facebook Messenger API for Python.
Most code structure were followed by `line-bot-sdk-python <https://github.com/line/line-bot-sdk-python>`__
Install
-------
::
$ pip install python-messengerbot-sdk
Synopsis
--------
Usage:
.. code:: python
from flask import Flask, request
from facebookbot import (
FacebookBotApi, WebhookHandler
)
from facebookbot.models import (
TextMessageEvent, TextSendMessage, TextSendMessage
)
app = Flask(__name__)
facebook_bot_api = FacebookBotApi("YOUR_PAGE_ACCESS_TOKEN")
handler = WebhookHandler()
@app.route('/callback', methods=['GET'])
def verify():
# when the endpoint is registered as a webhook, it must echo back
# the 'hub.challenge' value it receives in the query arguments
if request.args.get("hub.mode") == "subscribe" and request.args.get("hub.challenge"):
if not request.args.get("hub.verify_token") == "YOUR_VERIFY_TOKEN":
return "Verification token mismatch", 403
return request.args["hub.challenge"], 200
return "Hello world", 200
@app.route('/callback', methods=['POST'])
def webhook():
# endpoint for processing incoming messaging events
body = request.get_json()
handler.handle(body)
return "ok", 200
@handler.add(TextMessageEvent)
def handle_text_message(event):
facebook_bot_api.push_message(
event.sender.id,
message=TextSendMessage(text=event.message.text)
)
if __name__ == "__main__":
app.run()
API
---
MessengerBotApi
~~~~~~~~~~
\_\_init\_\_(self, page\_access\_token, endpoint='https://graph.facebook.com', timeout=5, http\_client=RequestsHttpClient)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create a new FacebookBotApi instance.
.. code:: python
facebook_bot_api = facebookbot.LineBotApi('YOUR_PAGE_ACCESS_TOKEN')
You can override the ``timeout`` value for each method.
push\_message(self, user\_id, message, is\_sender\_action = True, timeout = None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Send messages to users
.. code:: python
facebook_bot_api.push_message(user_id, TextSendMessage(text='Hello World!'))
broadcast(self, message, notification\_type="REGULAR", timeout = 60)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
broadcast to all page followers but limited to 10,000 per message.
.. code:: python
facebook_bot_api.broadcast(TextSendMessage(text='Hello World!'))
get\_profile(self, user\_id, timeout=None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Get user profile information.
.. code:: python
profile = facebook_bot_api.get_profile(user_id)
print(profile.first_name)
print(profile.last_name)
print(profile.gender)
print(profile.profile_pic)
print(profile.locale)
print(profile.timezone)
setup\_started\_button(self, timeout=None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
setup started button, when press it, then responding from GetStartedEvent
.. code:: python
facebook_bot_api.setup_started_button()
setup\_persistent\_menu(self, persistent\_menus, timeout=None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
setup persistent menu
.. code:: python
persistent_menus=[
PersistentMenu(
call_to_actions=[
NestedAction(
title="nested_title",
call_to_actions=[
PostbackAction(title="nested_postback", payload="nested_postback"),
URLAction(title="nested_url", url='https://example.com/')
]
),
PostbackAction(title="postback", payload="action=buy&itemid=1"),
URLAction(title="url", url='https://example.com/')
]
)
]
facebook_bot_api.setup_persistent_menu(persistent_menus)
upload\_attachment(self, attachment\_send\_message, timeout=None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
upload attachment to reuse and get attachment_id
.. code:: python
image = ImageSendMessage(image_url="pic_url.jpg")
attachment_id = facebook_bot_api.upload_attachment(image)
print(attachment_id)
Message objects
~~~~~~~~~~~~~~~
The following classes are found in the ``facebookbot.models`` package.
TextSendMessage
^^^^^^^^^^^^^^^
.. code:: python
text_message = TextSendMessage(text='Hello, world')
ImageSendMessage
^^^^^^^^^^^^^^^^
.. code:: python
image_message = ImageSendMessage(
image_url='https://example.com/original.jpg',
is_reusable=True
)
VideoSendMessage
^^^^^^^^^^^^^^^^
.. code:: python
video_message = VideoSendMessage(
video_url='https://example.com/original.mp4',
is_reusable=True
)
AudioSendMessage
^^^^^^^^^^^^^^^^
.. code:: python
audio_message = AudioSendMessage(
audio_url='https://example.com/original.m4a',
is_reusable=True
)
FileSendMessage
^^^^^^^^^^^^^^^^
.. code:: python
file_message = FileSendMessage(
file_url='https://example.com/original.pdf',
is_reusable=True
)
TemplateSendMessage - ButtonsTemplate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
buttons_template_message = TemplateSendMessage(
template=ButtonsTemplate(
text="Buttons template",
buttons=[
PostbackAction(
title="postback",
payload="action=buy&itemid=1"
),
URLAction(
title="url",
url="http://example.com/",
webview_height_ratio='full',
messenger_extensions=None,
fallback_url=None
)
]
)
)
TemplateSendMessage - GenericTemplate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
generic_template_message = TemplateSendMessage(
template=GenericTemplate(
elements=[
GenericElement(
title="GenericElement 1",
image_url="https://example.com/item1.jpg",
subtitle="description1",
default_action=URLAction(url="http://example.com/"),
buttons=[
PostbackAction(title="postback_1", payload="data_1"),
URLAction(
title="url_1",
url="http://example.com/1",
webview_height_ratio='full',
messenger_extensions=None,
fallback_url=None
)
]
),
GenericElement(
title="GenericElement 2",
image_url="https://example.com/item2.jpg",
subtitle="description2",
default_action=URLAction(url="http://example.com/"),
buttons=[
PostbackAction(title="postback_2", payload="data_2"),
URLAction(
title="url_2",
url="http://example.com/2",
webview_height_ratio='compact',
messenger_extensions=None,
fallback_url=None
)
]
)
]
)
)
TemplateSendMessage - MediaTemplate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By attachment_id
.. code:: python
media_template_message = TemplateSendMessage(
template=MediaTemplate(
elements=[
ImageElement(
attachment_id=attachment_id,
buttons=[
PostbackAction(title="postback_1", payload="data_1"),
URLAction(
title="url_1",
url="http://example.com/1",
webview_height_ratio='full',
messenger_extensions=None,
fallback_url=None
)
]
)
]
)
)
By facebook_url
.. code:: python
media_template_message = TemplateSendMessage(
template=MediaTemplate(
elements=[
ImageElement(
url="https://www.facebook.com/photo.php?fbid=<NUMERIC_ID>",
buttons=[
PostbackAction(title="postback_1", payload="data_1"),
URLAction(
title="url_1",
url="http://example.com/1",
webview_height_ratio='full',
messenger_extensions=None,
fallback_url=None
)
]
)
]
)
)
Hints
-----
Examples
~~~~~~~~
`object-example <https://github.com/boompieman/python-messengerbot-sdk>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
===================
SDK of the Facebook Messenger API for Python.
Most code structure were followed by `line-bot-sdk-python <https://github.com/line/line-bot-sdk-python>`__
Install
-------
::
$ pip install python-messengerbot-sdk
Synopsis
--------
Usage:
.. code:: python
from flask import Flask, request
from facebookbot import (
FacebookBotApi, WebhookHandler
)
from facebookbot.models import (
TextMessageEvent, TextSendMessage, TextSendMessage
)
app = Flask(__name__)
facebook_bot_api = FacebookBotApi("YOUR_PAGE_ACCESS_TOKEN")
handler = WebhookHandler()
@app.route('/callback', methods=['GET'])
def verify():
# when the endpoint is registered as a webhook, it must echo back
# the 'hub.challenge' value it receives in the query arguments
if request.args.get("hub.mode") == "subscribe" and request.args.get("hub.challenge"):
if not request.args.get("hub.verify_token") == "YOUR_VERIFY_TOKEN":
return "Verification token mismatch", 403
return request.args["hub.challenge"], 200
return "Hello world", 200
@app.route('/callback', methods=['POST'])
def webhook():
# endpoint for processing incoming messaging events
body = request.get_json()
handler.handle(body)
return "ok", 200
@handler.add(TextMessageEvent)
def handle_text_message(event):
facebook_bot_api.push_message(
event.sender.id,
message=TextSendMessage(text=event.message.text)
)
if __name__ == "__main__":
app.run()
API
---
MessengerBotApi
~~~~~~~~~~
\_\_init\_\_(self, page\_access\_token, endpoint='https://graph.facebook.com', timeout=5, http\_client=RequestsHttpClient)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create a new FacebookBotApi instance.
.. code:: python
facebook_bot_api = facebookbot.LineBotApi('YOUR_PAGE_ACCESS_TOKEN')
You can override the ``timeout`` value for each method.
push\_message(self, user\_id, message, is\_sender\_action = True, timeout = None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Send messages to users
.. code:: python
facebook_bot_api.push_message(user_id, TextSendMessage(text='Hello World!'))
broadcast(self, message, notification\_type="REGULAR", timeout = 60)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
broadcast to all page followers but limited to 10,000 per message.
.. code:: python
facebook_bot_api.broadcast(TextSendMessage(text='Hello World!'))
get\_profile(self, user\_id, timeout=None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Get user profile information.
.. code:: python
profile = facebook_bot_api.get_profile(user_id)
print(profile.first_name)
print(profile.last_name)
print(profile.gender)
print(profile.profile_pic)
print(profile.locale)
print(profile.timezone)
setup\_started\_button(self, timeout=None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
setup started button, when press it, then responding from GetStartedEvent
.. code:: python
facebook_bot_api.setup_started_button()
setup\_persistent\_menu(self, persistent\_menus, timeout=None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
setup persistent menu
.. code:: python
persistent_menus=[
PersistentMenu(
call_to_actions=[
NestedAction(
title="nested_title",
call_to_actions=[
PostbackAction(title="nested_postback", payload="nested_postback"),
URLAction(title="nested_url", url='https://example.com/')
]
),
PostbackAction(title="postback", payload="action=buy&itemid=1"),
URLAction(title="url", url='https://example.com/')
]
)
]
facebook_bot_api.setup_persistent_menu(persistent_menus)
upload\_attachment(self, attachment\_send\_message, timeout=None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
upload attachment to reuse and get attachment_id
.. code:: python
image = ImageSendMessage(image_url="pic_url.jpg")
attachment_id = facebook_bot_api.upload_attachment(image)
print(attachment_id)
Message objects
~~~~~~~~~~~~~~~
The following classes are found in the ``facebookbot.models`` package.
TextSendMessage
^^^^^^^^^^^^^^^
.. code:: python
text_message = TextSendMessage(text='Hello, world')
ImageSendMessage
^^^^^^^^^^^^^^^^
.. code:: python
image_message = ImageSendMessage(
image_url='https://example.com/original.jpg',
is_reusable=True
)
VideoSendMessage
^^^^^^^^^^^^^^^^
.. code:: python
video_message = VideoSendMessage(
video_url='https://example.com/original.mp4',
is_reusable=True
)
AudioSendMessage
^^^^^^^^^^^^^^^^
.. code:: python
audio_message = AudioSendMessage(
audio_url='https://example.com/original.m4a',
is_reusable=True
)
FileSendMessage
^^^^^^^^^^^^^^^^
.. code:: python
file_message = FileSendMessage(
file_url='https://example.com/original.pdf',
is_reusable=True
)
TemplateSendMessage - ButtonsTemplate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
buttons_template_message = TemplateSendMessage(
template=ButtonsTemplate(
text="Buttons template",
buttons=[
PostbackAction(
title="postback",
payload="action=buy&itemid=1"
),
URLAction(
title="url",
url="http://example.com/",
webview_height_ratio='full',
messenger_extensions=None,
fallback_url=None
)
]
)
)
TemplateSendMessage - GenericTemplate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
generic_template_message = TemplateSendMessage(
template=GenericTemplate(
elements=[
GenericElement(
title="GenericElement 1",
image_url="https://example.com/item1.jpg",
subtitle="description1",
default_action=URLAction(url="http://example.com/"),
buttons=[
PostbackAction(title="postback_1", payload="data_1"),
URLAction(
title="url_1",
url="http://example.com/1",
webview_height_ratio='full',
messenger_extensions=None,
fallback_url=None
)
]
),
GenericElement(
title="GenericElement 2",
image_url="https://example.com/item2.jpg",
subtitle="description2",
default_action=URLAction(url="http://example.com/"),
buttons=[
PostbackAction(title="postback_2", payload="data_2"),
URLAction(
title="url_2",
url="http://example.com/2",
webview_height_ratio='compact',
messenger_extensions=None,
fallback_url=None
)
]
)
]
)
)
TemplateSendMessage - MediaTemplate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By attachment_id
.. code:: python
media_template_message = TemplateSendMessage(
template=MediaTemplate(
elements=[
ImageElement(
attachment_id=attachment_id,
buttons=[
PostbackAction(title="postback_1", payload="data_1"),
URLAction(
title="url_1",
url="http://example.com/1",
webview_height_ratio='full',
messenger_extensions=None,
fallback_url=None
)
]
)
]
)
)
By facebook_url
.. code:: python
media_template_message = TemplateSendMessage(
template=MediaTemplate(
elements=[
ImageElement(
url="https://www.facebook.com/photo.php?fbid=<NUMERIC_ID>",
buttons=[
PostbackAction(title="postback_1", payload="data_1"),
URLAction(
title="url_1",
url="http://example.com/1",
webview_height_ratio='full',
messenger_extensions=None,
fallback_url=None
)
]
)
]
)
)
Hints
-----
Examples
~~~~~~~~
`object-example <https://github.com/boompieman/python-messengerbot-sdk>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
Close
Hashes for python-messengerbot-sdk-0.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | bd2231a5da83b4659fea117bb203b01fe7087932fa5a1937ede96667819c4a21 |
|
MD5 | 80da8abbaebd9950e94043b41892c680 |
|
BLAKE2b-256 | 8e9b0ebd291587f3f75b20a6f0fc0fe4da56f899e2d34664b53d355986d3eb99 |