Metadata-Version: 1.1
Name: fbmessenger
Version: 3.1.0
Summary: A python library to communicate with the Facebook Messenger API's
Home-page: https://github.com/rehabstudio/fbmessenger
Author: Ricky Dunlop
Author-email: ricky@rehabstudio.com
License: Apache
Description: Facebook Messenger
        ==================
        
        |PyPI| |Build Status| |Coverage Status| |PyPI|
        
        A python library to communicate with the Facebook Messenger API's
        
        Installation
        ------------
        
        Install from pip
        
        ::
        
            pip install fbmessenger
        
        Facebook app setup
        ------------------
        
        -  `Create a page <https://www.facebook.com/pages/create/>`__ for your
           app, if you don't already have one
        -  `Create an
           app <https://developers.facebook.com/quickstarts/?platform=web>`__
        -  Add the Messenger product
        -  Select the Page to generate a page token
        
        Example usage with Flask
        ------------------------
        
        First you need to create a verify token, this can be any string e.g.
        
        ::
        
            'my_verify_token'
        
        Messenger class
        ~~~~~~~~~~~~~~~
        
        We need to extend the ``BaseMessenger`` abstract class and implement
        methods for each of the following subscription fields.
        
        -  ``message``
        -  ``delivery``
        -  ``read``
        -  ``optin``
        -  ``postback``
        -  ``account_linking``
        
        .. code:: python
        
            from fbmessenger import BaseMessenger
        
        
            class Messenger(BaseMessenger):
                def __init__(self, page_access_token):
                    self.page_access_token = page_access_token
                    super(Messenger, self).__init__(self.page_access_token)
        
                def message(self, message):
                    self.send({'text': 'Received: {0}'.format(message['message']['text'])})
        
                def delivery(self, message):
                    pass
        
                def read(self, message):
                    pass
        
                def account_linking(self, message):
                    pass
        
                def postback(self, message):
                    pass
        
                def optin(self, message):
                    pass
        
        Create a route for the callback url
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        This can be used to process any messages received and also to verify
        your app
        
        .. code:: python
        
            import os
            from flask import Flask, request
        
            app = Flask(__name__)
            app.debug = True
        
            messenger = Messenger(os.environ.get('FB_VERIFY_TOKEN'), os.environ.get('FB_PAGE_TOKEN'))
        
            @app.route('/webhook', methods=['GET', 'POST'])
            def webhook():
                if request.method == 'GET':
                    if (request.args.get('hub.verify_token') == os.environ.get('FB_VERIFY_TOKEN')):
                        return request.args.get('hub.challenge')
                    raise ValueError('FB_VERIFY_TOKEN does not match.')
                elif request.method == 'POST':
                    messenger.handle(request.get_json(force=True))
                return ''
        
        
            if __name__ == "__main__":
                app.run(host='0.0.0.0')
        
        Elements
        --------
        
        Import the elements (or just the ones you need)
        
        ::
        
            from fbmessenger import elements
        
        Text
        ~~~~
        
        You can pass a simple dict or use the Class
        
        .. code:: python
        
            messenger.send({'text': msg})
        
            elem = elements.Text('Your Message')
            messenger.send(elem.to_dict())
        
        Web button
        ~~~~~~~~~~
        
        .. code:: python
        
            btn = elements.Button(title='Web button', url='http://example.com')
            messenger.send(btn.to_dict())
        
        Payload button
        ~~~~~~~~~~~~~~
        
        To use these buttons you must have the ``message_deliveries``
        subscription enabled
        
        .. code:: python
        
            btn = elements.Button(title='Postback button', payload='payload')
            messenger.send(btn.to_dict())
        
        Attachments
        -----------
        
        Images
        ~~~~~~
        
        .. code:: python
        
            image = attachments.Image(url='http://example.com/image.jpg')
            messenger.send(image.to_dict())
        
        Audio
        ~~~~~
        
        .. code:: python
        
            audio = attachments.Image(url='http://example.com/audio.mp3')
            messenger.send(audio.to_dict())
        
        Video
        ~~~~~
        
        .. code:: python
        
            video = attachments.Video(url='http://example.com/video.mp4')
            messenger.send(video.to_dict())
        
        Files
        ~~~~~
        
        .. code:: python
        
            file = attachments.File(url='http://example.com/file.txt')
            messenger.send(file.to_dict())
        
        Templates
        ---------
        
        Import the templates (or just the ones you need)
        
        ::
        
            from fbmessenger import templates
        
        Generic template
        ~~~~~~~~~~~~~~~~
        
        .. code:: python
        
            btn = elements.Button(title='Web button', url='http://facebook.com')
            elems = elements.Element(
                title='Element',
                item_url='http://facebook.com',
                image_url='http://facebook.com/image.jpg',
                subtitle='Subtitle',
                buttons=[
                    btn
                ]
            )
            res = templates.GenericTemplate(elements=[elems])
            messenger.send(res.to_dict())
        
        Button template
        ~~~~~~~~~~~~~~~
        
        .. code:: python
        
            btn = elements.Button(title='Web button', url='http://facebook.com')
            btn2 = elements.Button(title='Postback button', payload='payload')
            res = templates.ButtonTemplate(
                text='Button template',
                buttons=[btn, btn2]
            )
            messenger.send(res.to_dict())
        
        Receipt template
        ~~~~~~~~~~~~~~~~
        
        .. code:: python
        
            element = elements.Element(
                title='Classic White T-Shirt',
                subtitle='100% Soft and Luxurious Cotton',
                quantity=2,
                price=50,
                currency='USD',
                image_url='http://petersapparel.parseapp.com/img/whiteshirt.png',
            )
            adjustment1 = elements.Adjustment(name='New Customer Discount', amount=20)
            adjustment2 = elements.Adjustment(name='$10 Off Coupon', amount=10)
            address = elements.Address(
                street_1='1 Hacker Way',
                city='Menlo Park',
                postal_code='94025',
                state='CA',
                country='US'
            )
            summary = elements.Summary(
                subtotal=75.00,
                shipping_cost=4.95,
                total_tax=6.19,
                total_cost=56.14
            )
            res = templates.ReceiptTemplate(
                recipient_name='Stephane Crozatier',
                order_number='12345678902',
                currency='USD',
                payment_method='Visa 2345',
                order_url='http://petersapparel.parseapp.com/order?order_id=123456',
                timestamp='1428444852',
                address=address,
                summary=summary,
                adjustments=[adjustment1, adjustment2],
                elements=[element]
            )
            messenger.send(res.to_dict())
        
        Sender Actions
        --------------
        
        Typing on
        ~~~~~~~~~
        
        .. code:: python
        
            typing_on = SenderAction(sender_action='typing_on')
            messenger.send_action(typing_on.to_dict())
        
        Typing off
        ~~~~~~~~~~
        
        .. code:: python
        
            typing_ffn = SenderAction(sender_action='typing_off')
            messenger.send_action(typing_off.to_dict())
        
        Mark seen
        ~~~~~~~~~
        
        .. code:: python
        
            mark_seen = SenderAction(sender_action='mark_seen')
            messenger.send_action(mark_seen.to_dict())
        
        Quick Replies
        -------------
        
        .. code:: python
        
            quick_reply_1 = QuickReply(title='Do something', payload='Send me this payload')
            quick_reply_2 = QuickReply(title='Do something else', payload='Send me this other payload')
            quick_replies = QuickReplies(quick_replies=[
                quick_reply_1,
                quick_reply_2
            ])
            text = { text: 'A message' }
            text['quick_replies'] = quick_replies.to_dict()
            messenger.send(text)
        
        Thread settings
        ---------------
        
        Greeting Text
        ~~~~~~~~~~~~~
        
        .. code:: python
        
        
            from fbmessenger.thread_settings import GreetingText
        
            greeting_text = new GreetingText('Welcome to my bot')
            messenger.send(greeting_text.to_dict())
        
        Get Started Button
        ~~~~~~~~~~~~~~~~~~
        
        .. code:: python
        
            from fbmessenger.thread_settings import GetStartedButton
        
            get_started = new GetStartedButton(payload='GET_STARTED')
            messenger.send(get_started.to_dict())
        
        You can then check for this payload in the ``postback`` method
        
        Persistent Menu
        ~~~~~~~~~~~~~~~
        
        .. code:: python
        
            from fbmessenger.thread_settings import PersistentMenu, PersistentMenuItem
        
            menu_item_1 = new PersistentMenuItem(item_type='web_url', title='Menu Item 1', url='https://facebook.com')
            menu_item_2 = new PersistentMenuItem(item_type='postback', title='Menu Item 2', payload='PAYLOAD')
        
            menu = new PersistentMenu(menu_items=[menu_item_1, menu_item_2])
        
            messenger.send(menu.to_dict())
        
        Code Contributions
        ------------------
        
        When contributing code, you'll want to follow this checklist:
        
        1. Fork the repository on GitHub.
        2. Run the tests to confirm they all pass on your system. If they don't,
           you'll need to investigate why they fail. If you're unable to
           diagnose this yourself, raise it as a bug report by following the
           guidelines in this document: Bug Reports.
        3. Write tests that demonstrate your bug or feature. Ensure that they
           fail.
        4. Make your change.
        5. Run the entire test suite again, confirming that all tests pass
           including the ones you just added.
        6. Send a GitHub Pull Request to the main repository's master branch. 7.
           GitHub Pull Requests are the expected method of code collaboration on
           this project.
        
        Creating a new release
        ~~~~~~~~~~~~~~~~~~~~~~
        
        *nb. `Pandoc <http://pandoc.org/installing.html>`__ is required as it is
        used to convert the README to reStructuredText format*
        
        -  Commit latest changes
        -  Update in ``__version__`` in ``init.py``
        
        .. code:: bash
        
            git push --tags
            python setup.py sdist bdist_wheel
            twine upload -r pypi dist/fbmessenger-<version>*
        
        .. |PyPI| image:: https://img.shields.io/pypi/v/fbmessenger.svg?maxAge=2592000
           :target: https://pypi.python.org/pypi/fbmessenger
        .. |Build Status| image:: https://travis-ci.org/rehabstudio/fbmessenger.svg?branch=master
           :target: https://travis-ci.org/rehabstudio/fbmessenger
        .. |Coverage Status| image:: https://coveralls.io/repos/github/rehabstudio/fbmessenger/badge.svg?branch=master
           :target: https://coveralls.io/github/rehabstudio/fbmessenger?branch=master
        .. |PyPI| image:: https://img.shields.io/pypi/l/fbmessenger.svg?maxAge=2592000
           :target: https://pypi.python.org/pypi/fbmessenger
        
Keywords: Facebook Messenger
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
