(Deprecated Project)

FBMQ (Facebook Messenger Platform Python Library)

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
• Handle webhook
  • usage (with flask)
  • handlers
• Send a message
  • basic
    • text
    • image / audio / video / file
    • quick reply
      • quick reply callback
    • typing on/off
  • templates
    • button
      • button callback
    • generic
    • receipt
  • options
    • notification type
    • callback
• Thread settings
  • greeting text
  • get started button
  • persistent menu
• Fetch user/page profile
• Example

Install

pip install fbmq

Handle webhook

how to handle messages from user to facebook page

Usage (with flask)

from flask import Flask, request
from fbmq import Page

page = 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):
  """:type event: fbmq.Event"""
  sender_id = event.sender_id
  message = event.message_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. (quick reply is also handled in here)

@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 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.

@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

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

event.quick_reply_payload str : `event.quick_reply.get('payload')

event.postback dict : postback dict that is received. more detail

event.postback_payload str : `event.postback.get('payload')

event.optin dict : dict that is received. more detail

event.account_linking dict: dict that is received. more detail

event.delivery dict: dict that is received. more detail

event.read dict: dict that is received. more detail

event.is_* bool - True if event type is valid

if you don't need a decorator

page = fbmq.Page(PAGE_ACCESS_TOKEN, after_send=after_send)

@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):
  """:type event: fbmq.Event"""
  sender_id = event.sender_id
  message = event.message_text
  
  page.send(sender_id, "thank you! your message is '%s'" % message)

def after_send(payload, response):
  """:type event: fbmq.Payload"""
  print("complete")

Send a message

how to send a message from facebook page to user

Basic

Import

from fbmq import Attachment, Template, QuickReply, Page

Text

page.send(recipient_id, "hello world!")

Image

jpg, png, gif support

page.send(recipient_id, Attachment.Image(image_url))

Audio

page.send(recipient_id, Attachment.Audio(audio_url))

Video

page.send(recipient_id, Attachment.Video(video_url))

File

page.send(recipient_id, Attachment.File(file_url))

quick reply

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.

@page.callback(['PICK_ACTION', 'PICK_COMEDY'])
def callback_picked_genre(payload, event):
  print(payload, event)
  
# Also supported regex, it works corretly
# @page.callback(['PICK_(.+)'])

if you want to handle only quick_reply callback without button postback

@page.callback(['PICK_ACTION', 'PICK_COMEDY'], types=['QUICK_REPLY'])

typing on/off

page.typing_on(recipient_id)
page.typing_off(recipient_id)

Templates

Template : Button

buttons = [
  Templates.ButtonWeb("Open Web URL", "https://www.oculus.com/en-us/rift/"),
  Templates.ButtonPostBack("trigger Postback", "DEVELOPED_DEFINED_PAYLOAD"),
  Templates.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).

@page.callback(['DEVELOPED_DEFINED_PAYLOAD'])
def callback_clicked_button(payload, event):
  print(payload, event)
  
# Also supported regex, it works corretly
# @page.callback(['DEVELOPED_DEFINE(.+)'])

if you want to handle only button's postback without quick_reply callback

@page.callback(['DEVELOPED_DEFINED_PAYLOAD'], types=['POSTBACK'])

Template : Generic

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

    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)

    page.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]))

Options

notification type

support notification_type as a option

NotificationType.REGULAR (default), NotificationType.SILENT_PUSH, NotificationType.NO_PUSH

page.send(recipient_id, 'hello', notification_type=NotificationType.NO_PUSH)

callback

you can set a callback function to each page.send

def callback(payload, response):
  print('response : ' + response.text)
  
page.send(recipient_id, 'hello', callback=callback)

Thread settings

Greeting text

page.greeting("Welcome!")

Get started button

page.show_starting_button("START_PAYLOAD")

@page.callback(['START_PAYLOAD'])
def start_callback(payload, event):
  print("Let's start!")

Persistent menu

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)

Fetch user/page profile

page_id = page.page_id
page_name = page.page_name
user_profile = page.get_user_profile(event.sender_id) # return dict
print(user_profile)

#{"first_name":"...", "last_name":"...", "profile_pic":"...", "locale":"...", "timezone":9, "gender":"..."}

Example

1. fill example/config.py
2. run server

cd example
virtualenv env
source env/bin/activate
pip install -r requirements.txt
python server.py