python-messengerbot-sdk 0.1.0
Facebook Messaging API SDK for Python
License: Apache License 2.0

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>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^