Merge branch 'develop'

CHANGELOG

@@ -4,6 +4,15 @@ FBMQ Changelog
 Latest
 ------
 
+2.0.0
+-----
+
+* Feature : All of page handlers have parameter Event instead of a dict.
+* Feature : Support a thread setting
+* Deprecated : remove callback_postback, callback_quick_reply
+* Feature : Add a decorator - page.callback(['payload'], types=['QUICK_REPLY', 'POSTBACK'])
+* Feature : Add a page method, get_user_profile(fb_user_id), to get facebook user profile
+
 1.7.0
 -----
 
@@ -21,4 +30,4 @@ Latest
 -----
 
 * Support decorators (message handlers and button/quickreply callbacks)
-* Deprecated fbmq.handler_webhook method (must use page.handler_webhoo)
+* Deprecated fbmq.handler_webhook method (must use page.handler_webhoo)

README.md

@@ -27,6 +27,10 @@ Facebook messenger platform api full features are supported
   * [options](#options)
     * [notification type](#notification-type)
     * [callback](#callback) 
+* [Thread settings](#thread-settings)
+  * [greeting text](#greeting-text)
+  * [get started button](#get-started-button)
+  * [persistent menu](#persistent-menu)
 * [Example](#example)
 
 
@@ -52,20 +56,22 @@ def webhook():
 
 @page.handle_message
 def message_handler(event):
-  sender_id = event['sender']['id']
-  message = event['message']
+  """:type event: fbmq.Event"""
+  sender_id = event.sender_id
+  message = event.message_text
 
-  page.send(sender_id, "thank you! your message is '%s'" % message.get('text'))
+  page.send(sender_id, "thank you! your message is '%s'" % message)
 
 @page.after_send
 def after_send(payload, response):
+  """:type payload: fbmq.Payload"""
   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_message` - This callback will occur when a message has been sent to your page. (`quick reply` is also handled in here)
 
 `@page.handle_echo` - This callback will occur when a message has been sent by your page
 
@@ -81,6 +87,39 @@ A spec in detail - https://developers.facebook.com/docs/messenger-platform/webho
 
 `@page.after_send` - This callback will occur when page.send function has been called.
 
+#### Event parameter (fbmq.Event class)
+
+`event.sender_id` _str_ : message sender id, user id
+
+`event.recipient_id` _str_ : message receiver id, page id
+
+`event.timestamp` _number_ : timestamp when message is received
+
+`event.message` _dict_ : message dict that is received. [more detail](https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-received)
+
+`event.message_text` _str_ : `event.message.get('text')`
+
+`event.message_attachments` _str_ : `event.message.get('attachments')`
+
+`event.quick_reply` _dict_ : quick reply dict that is received. [more detail](https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-received)
+
+`event.quick_reply_payload` _str_ : `event.quick_reply.get('payload')
+
+`event.postback` _dict_ : postback dict that is received. [more detail](https://developers.facebook.com/docs/messenger-platform/webhook-reference/postback-received)
+
+`event.postback_payload` _str_ : `event.postback.get('payload')
+
+`event.optin` _dict_ : dict that is received. [more detail](https://developers.facebook.com/docs/messenger-platform/webhook-reference/authentication)
+
+`event.account_linking` _dict_: dict that is received. [more detail](https://developers.facebook.com/docs/messenger-platform/account-linking)
+
+`event.delivery` _dict_: dict that is received. [more detail](https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-delivered)
+
+`event.read` _dict_: dict that is received. [more detail](https://developers.facebook.com/docs/messenger-platform/webhook-reference/message-read)
+
+
+`event.is_*` _bool_ - True if event type is valid
+
 #### if you don't need a decorator
 ```python
 page = fbmq.Page(PAGE_ACCESS_TOKEN, after_send=after_send)
@@ -92,12 +131,14 @@ def webhook():
   return "ok"
 
 def message_handler(event):
-  sender_id = event['sender']['id']
-  message = event['message']
+  """:type event: fbmq.Event"""
+  sender_id = event.sender_id
+  message = event.message_text
 
-  page.send(sender_id, "thank you! your message is '%s'" % message.get('text'))
+  page.send(sender_id, "thank you! your message is '%s'" % message)
 
 def after_send(payload, response):
+  """:type event: fbmq.Payload"""
   print("complete")
 ```
 
@@ -164,14 +205,18 @@ page.send(recipient_id,
 ##### quick reply callback
 you can define easily a quick reply callback method.
 ```python
-@page.callback_quick_reply(['PICK_ACTION', 'PICK_COMEDY'])
+@page.callback(['PICK_ACTION', 'PICK_COMEDY'])
 def callback_picked_genre(payload, event):
   print(payload, event)
 
 # Also supported regex, it works corretly
-# @page.callback_quick_reply(['PICK_(.+)'])
+# @page.callback(['PICK_(.+)'])
 ```
 
+if you want to handle only quick_reply callback without button postback
+```python
+@page.callback(['DEVELOPED_DEFINED_PAYLOAD'], types=['QUICK_REPLY'])
+```
 
 ##### typing on/off
 ```python
@@ -203,12 +248,17 @@ page.send(recipient_id, Template.Buttons("hello", buttons))
 ##### button callback
 you can define easily a button postback method (it works only postback type buttons).
 ```python
-@page.callback_button(['DEVELOPED_DEFINED_PAYLOAD'])
+@page.callback(['DEVELOPED_DEFINED_PAYLOAD'])
 def callback_clicked_button(payload, event):
   print(payload, event)
 
 # Also supported regex, it works corretly
-# @page.callback_button(['DEVELOPED_DEFINE(.+)'])
+# @page.callback(['DEVELOPED_DEFINE(.+)'])
+```
+
+if you want to handle only button's postback without quick_reply callback
+```python
+@page.callback(['DEVELOPED_DEFINED_PAYLOAD'], types=['POSTBACK'])
 ```
 
 
@@ -290,6 +340,32 @@ def callback(payload, response):
 page.send(recipient_id, 'hello', callback=callback)
 ```
 
+# Thread settings
+### Greeting text
+```python
+page.greeting("Welcome!")
+```
+
+### Get started button
+```python
+page.show_starting_button("START_PAYLOAD")
+
+@page.callback(['START_PAYLOAD'])
+def start_callback(payload, event):
+  print("Let's start!")
+```
+
+### Persistent menu
+```python
+page.show_persistent_menu([Template.ButtonPostBack('MENU1', 'MENU_PAYLOAD/1'),
+                           Template.ButtonPostBack('MENU2', 'MENU_PAYLOAD/2')])
+
+@page.callback(['MENU_PAYLOAD/(.+)'])
+def click_persistent_menu(payload, event):
+  click_menu = payload.split('/')[1]
+  print("you clicked %s menu" % click_menu)
+```
+
 # Example
 
 1. fill example/config.py

example/config.py

@@ -1,5 +1,5 @@
 CONFIG = {
-    'FACEBOOK_TOKEN': 'TOKEN',
-    'VERIFY_TOKEN': 'TOKEN',
-    'SERVER_URL': 'https://webhook_host'
+    'FACEBOOK_TOKEN': 'EAANgzn2wUtoBADwVamrsDaGZBRrFiEKz7UXtpALkmiH1WNzBPZCtbvbSsDGGZAbmBbdJZChg7ivMMdURQAwiRCsoiB41LDC8haMUzSutGti88ebZBx5smzLpR0xMzjlsfetrrCdWdcjTq8Onhr0bbZB11l67YKuV0OpQpalmFgLQZDZD',
+    'VERIFY_TOKEN': 'verify_simsimbot',
+    'SERVER_URL': 'https://karl.ohrocks.com'
 }

example/fbpage.py

@@ -1,5 +1,10 @@
+# coding: utf-8
+import os
+parentdir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+os.sys.path.insert(0,parentdir)
+
 from fbmq import Page
-from config import CONFIG
+from example.config import CONFIG
 
 page = Page(CONFIG['FACEBOOK_TOKEN'])
 

example/messenger.py

@@ -1,18 +1,23 @@
+# coding: utf-8
+import os
+parentdir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+os.sys.path.insert(0,parentdir)
+
 import json
-from config import CONFIG
+from example.config import CONFIG
 from fbmq import Attachment, Template, QuickReply, NotificationType
-from fbpage import page
+from example.fbpage import page
 
 USER_SEQ = {}
 
 
 @page.handle_optin
 def received_authentication(event):
-    sender_id = event.get("sender", {}).get("id")
-    recipient_id = event.get("recipient", {}).get("id")
-    time_of_auth = event.get("timestamp")
+    sender_id = event.sender_id
+    recipient_id = event.recipient_id
+    time_of_auth = event.timestamp
 
-    pass_through_param = event.get("optin", {}).get("ref")
+    pass_through_param = event.optin.get("ref")
 
     print("Received authentication for user %s and page %s with pass "
           "through param '%s' at %s" % (sender_id, recipient_id, pass_through_param, time_of_auth))
@@ -22,7 +27,7 @@ def received_authentication(event):
 
 @page.handle_echo
 def received_echo(event):
-    message = event.get("message", {})
+    message = event.message
     message_id = message.get("mid")
     app_id = message.get("app_id")
     metadata = message.get("metadata")
@@ -32,10 +37,10 @@ def received_echo(event):
 
 @page.handle_message
 def received_message(event):
-    sender_id = event.get("sender", {}).get("id")
-    recipient_id = event.get("recipient", {}).get("id")
-    time_of_message = event.get("timestamp")
-    message = event.get("message", {})
+    sender_id = event.sender_id
+    recipient_id = event.recipient_id
+    time_of_message = event.timestamp
+    message = event.message
     print("Received message for user %s and page %s at %s with message:"
           % (sender_id, recipient_id, time_of_message))
     print(message)
@@ -70,7 +75,7 @@ def received_message(event):
 
 @page.handle_delivery
 def received_delivery_confirmation(event):
-    delivery = event.get("delivery", {})
+    delivery = event.delivery
     message_ids = delivery.get("mids")
     watermark = delivery.get("watermark")
 
@@ -83,11 +88,11 @@ def received_delivery_confirmation(event):
 
 @page.handle_postback
 def received_postback(event):
-    sender_id = event.get("sender", {}).get("id")
-    recipient_id = event.get("recipient", {}).get("id")
-    time_of_postback = event.get("timestamp")
+    sender_id = event.sender_id
+    recipient_id = event.recipient_id
+    time_of_postback = event.timestamp
 
-    payload = event.get("postback", {}).get("payload")
+    payload = event.postback_payload
 
     print("Received postback for user %s and page %s with payload '%s' at %s"
           % (sender_id, recipient_id, payload, time_of_postback))
@@ -97,17 +102,17 @@ def received_postback(event):
 
 @page.handle_read
 def received_message_read(event):
-    watermark = event.get("read", {}).get("watermark")
-    seq = event.get("read", {}).get("seq")
+    watermark = event.read.get("watermark")
+    seq = event.read.get("seq")
 
     print("Received message read event for watermark %s and sequence number %s" % (watermark, seq))
 
 
 @page.handle_account_linking
 def received_account_link(event):
-    sender_id = event.get("sender", {}).get("id")
-    status = event.get("account_linking", {}).get("status")
-    auth_code = event.get("account_linking", {}).get("authorization_code")
+    sender_id = event.sender_id
+    status = event.account_linking.get("status")
+    auth_code = event.account_linking.get("authorization_code")
 
     print("Received account link event with for user %s with status %s and auth code %s "
           % (sender_id, status, auth_code))
@@ -179,7 +184,7 @@ def send_button(recipient):
     ]))
 
 
-@page.callback_button(['DEVELOPED_DEFINED_PAYLOAD'])
+@page.callback(['DEVELOPED_DEFINED_PAYLOAD'])
 def callback_clicked_button(payload, event):
     print(payload, event)
 
@@ -258,7 +263,7 @@ def send_quick_reply(recipient):
               metadata="DEVELOPER_DEFINED_METADATA")
 
 
-@page.callback_quick_reply(['PICK_ACTION'])
+@page.callback(['PICK_ACTION'])
 def callback_picked_genre(payload, event):
     print(payload, event)
 

example/requirements.txt

@@ -1,3 +1,2 @@
 flask
-requests
-fbmq
+requests

example/server.py

@@ -1,10 +1,13 @@
 # coding: utf-8
+import os
+parentdir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+os.sys.path.insert(0,parentdir)
 
 from flask import Flask, request, send_from_directory, render_template
 
-import messenger
-from config import CONFIG
-from fbpage import page
+import example.messenger
+from example.config import CONFIG
+from example.fbpage import page
 
 app = Flask(__name__)
 

fbmq/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '1.7.0'
+__version__ = '2.0.0'
 
 from .fbmq import *
 from . import attachment as Attachment