Skip to content

Arhisan/Facebook-Bot-Library

This branch is up to date with keithwhitson/Facebook-Bot-Library:master.

Repository files navigation

Messenger SDK for Flask

Python Pypi Status

Facebook Messenger Platform SDK for Flask

Get started

Note: You need Flask to be installed

Installation

Easy to Setup via pip

$ pip install Facebook-Bot-Library

Installation via Git

$ git clone https://github.com/boosted-lab/Facebook-Bot-Library.git
$ python Facebook-Bot-Library/setup.py install

Usage

Receiving a message and sending a response example

from flask import request
from facebook_messaging.fbbot import FBBot
from facebook_messaging.order import FBOrder
from facebook_messaging.attachment import FBAttachment

token = "<your token>"
verify_token = "<your verify_token>"
bot = FBBot(token, verify_token)

@app.route('/webhook', methods=['GET', 'POST'])
def webhook():
    return bot.webhook(request, on_message, on_postback)

def on_postback(sender, text, requestInfo):
    # something to do

def on_message(sender, text, requestInfo):
    # something to do

Contents

Examples:

Reference:

Built-in methods for sending messages

Go to: Contents

Text message

FBBot.send_text_message(self, recipient_id, text, quick_replies = []) 
    '''
    @required:
        recipient_id
        text
    @optional:
        quick_replies array, up to ten replies, each is FBAttachment.quick_reply
    @output:
        response_json
    '''

# Example
bot.send_text_message(sender, "Hello, how can I help you?")

Message with attachment

FBBot.send_message_file_attachment(self, recipient_id, attachment_type, file_url, quick_replies = [])
   '''
   @required:
       recipient_id
       attachment_type from FBAttachment.File
       file_url
   @optional:
       quick_replies array, up to ten replies, each is FBAttachment.quick_reply
   @output:
       response_json
   '''
# Example (video attachment)
bot.send_message_file_attachment(sender, FBAttachment.File.video, 
   "http://img-9gag-fun.9cache.com/photo/adXLy8N_460sv.mp4")
   
# Example (image attachment)
bot.send_message_file_attachment(sender, FBAttachment.File.image, 
   "http://img-9gag-fun.9cache.com/photo/aEnxQve_460s_v1.jpg")

Creating message attachments

Use class FBAttachment for creating attachments to your messages

For creating postback buttons, web url buttons and quick replies there're few methods:

    FBAttachment.button_postback(title, postback)
    FBAttachment.button_web_url(title, url)
    FBAttachment.quick_reply(title)

Also, FBAttachment contents nested class File.

You should use these fieds of the class to obtain attachment_type

FBAttachment.File.image
FBAttachment.File.audio
FBAttachment.File.video
FBAttachment.File.file

Generic message

Use the Facebook's Generic template to send a message composed of an image attachment, short description and buttons to request input from the user. The buttons can open a URL, or make a callback to your webhook.

FBBot.send_message_generic(self, recipient_id, title, subtitle, image_url, buttons = [], quick_replies = [])
    '''
   @required:
       recipient_id
       title
       subtitle (may be empty string)
       image_url (may be empty string)
   @optional:
       buttons array, up to three buttons, each is FBAttachment.button
       quick_replies array, up to ten replies, each is FBAttachment.quick_reply
   @output:
       response_json
   '''
Example
buttons = [
            {
                "type": "web_url",
                "url": "https://www.google.com",
                "title": "View Google",

            },
            {
                "type": "web_url",
                "url": "https://www.yandex.com",
                "title": "View Yandex",

            },
            {
                "type": "postback",
                "title": "Back",
                "payload": "USER_BACK_PAYLOAD"
            }
        ]
        
bot.send_message_generic(sender, "Search engines' catalogue", "Select any",
                         "https://www.24k.com.sg/images/sem1.png",
                         buttons)

Generic example

Other template messages

FBBot.send_message_TypeC(self, recipient_id, template, quick_replies = [])
    '''
    @required:
        recipient_id
        template is instance of FBOrder or AirlineChekin, AirlineFlightUpdate, 
            AirlineItinerary or another class representing Messenger template
    @optional:
        quick_replies array, up to ten replies, each is FBAttachment.quick_reply...
    @output:
        response_json
    '''

Note

Every message may contain up to ten quick replies passed as last argument

bot.send_text_message(sender, "Pick a color:", [ 
    FBAttachment.quick_reply("Red"), 
    FBAttachment.quick_reply("Blue"),
    FBAttachment.quick_reply("Green")
])

Examples: Sending a template message

Airline Chekin template

Go to: Contents

Description at Facebook Developers

message = AirlineCheckin(
    "Checkin",
    "en_US",
    "12356",
    [
        AirlineCheckin.make_flight_info(
            "QR142",
            AirlineCheckin.make_airport("SIN", "Singapore"),
            AirlineCheckin.make_airport("DME", "Moscow"),
            AirlineCheckin.make_flight_schedule("2016-01-05T15:05", "2016-01-06T19:05")
        )
    ]
    , "https://google.com")
bot.send_message_TypeC(sender, message)

Will result in

Airline chekin example

AirlineChekin class reference

Go to: Contents

Constructor

AirlineChekin.__init__(self, intro_message, locale, pnr_number, flight_info, checkin_url, theme_color="")
    '''
    @required:
        intro_message
        locale
        pnr_number - booking number
        flight_info - Array of flight info objects
        chekin_url
    @optional:
        theme_color -  RGB hexadecimal string (default #009ddc)
    '''

Generating payload

AirlineChekin.get_payload(self)

Creating "flight info" object

AirlineChekin.make_flight_info(flight_number, departure_airport, arrival_airport, flight_schedule)
    '''
    @required:
        flight_number 
        departure_airport  - airport object
        arrival_airport - -//-
        flight_schedule - flight schedule object
    @output:
        Flight info JSON object
    '''

Creating "airport" object

AirlineChekin.make_airport(airport_code, city, terminal="", gate="")
    '''
    @required
        airport_code
        city
    @optional
        terminal
        gate
    @output
        Airport info JSON object
    '''

Generating "flight schedule" object

AirlineChekin.make_flight_schedule(departure_time, arrival_time, boarding_time="")
    '''
    @required:
        departure_time - time in 'YYYY-MM-DDThh:mm' format
        arrival_time
    @optional
        boarding_time
    @output:
        Flight schedule JSON object
    '''

Airline flight update template

Go to: Contents

Description at Facebook Developers

message = AirlineFlightUpdate(
    "UPD",
    "delay",
    "en_US",
    "12356",
    AirlineFlightUpdate.make_update_flight_info(
        "QR142",
        AirlineFlightUpdate.make_airport("SIN", "Singapore"),
        AirlineFlightUpdate.make_airport("DME", "Moscow"),
        AirlineFlightUpdate.make_flight_schedule("2016-01-05T15:35", "2016-01-07T19:35")
    )
)
bot.send_message_TypeC(sender, message)

Airline flight update example

AirlineFlightUpdate class reference

Go to: Contents

Constructor

AirlineFlightUpdate.__init__(self, intro_message, update_type, locale, pnr_number, 
                            update_flight_info, theme_color="")
    '''
    @required:
        intro_message
        update_type - must be "delay", "gate_change" or "cancellation"
        locale
        pnr_number - booking number
        update_flight_info
    @optional:
        theme_color -  RGB hexadecimal string (default #009ddc)
    '''

Creating updated flight info JSON object

AirlineFlightUpdate.make_update_flight_info(flight_number, departure_airport, arrival_airport, flight_schedule)
    '''
    @required:
        flight_number
        departure_airport
        arrival_airport
        flight_schedule
    @output:
        Flight information JSON object
    '''

Generating "airport" object

AirlineFlightUpdate.make_airport(airport_code, city, terminal="", gate="")
    '''
    @required:
        airport_code
        city
    @optional:
        terminal
        gate
    @output:
        Airport info JSON object
    '''

Creating "flight schedule" object

AirlineFlightUpdate.make_flight_schedule(departure_time, arrival_time="", boarding_time="")
    '''
    @required
        departure_time
    @optional
        arrival_time
        boarding_time
    @output:
        Flight schedule JSON object
    '''

Generating payload

AirlineFlightUpdate.get_payload(self)
    '''
    @output:
        payload
    '''

Airline Boarding Pass template

Go to: Contents

Description at Facebook Developers

message = AirlineBoardingPass(
            "someticket",
            "en_US",
            [
                AirlineBoardingPass.boarding_pass_item(
                    "Michel",
                    "http://ausbb.com/1/celts049.jpg",
                    "SAV45",
                    "",
                    "http://www.imgonline.com.ua/examples/qr-code.png",
                    "http://www.swissarmylibrarian.net/wp-content/uploads/2011/02/barcodelunch.png",
                    "business",
                    AirlineBoardingPass.flight_info(
                        "QR142",
                        AirlineFlightUpdate.make_airport("SIN","Singapore"),
                        AirlineFlightUpdate.make_airport("DME","Moscow"),
                        AirlineFlightUpdate.make_flight_schedule("2016-01-05T15:35","2016-01-07T19:35")
                    )
                )
            ]
        )

    bot.send_message_TypeC(sender, message)

Airline boarding pass example Airline boarding pass example

AirlineBoardingPass class reference

Go to: Contents

Constructor

AirlineBoardingPass.__init__(self, intro_message, locale, boarding_pass, theme_color="")
    '''
    @required:
        intro_message
        locale
        boarding_pass - JSON boarding pass item
    @optional:
        theme_color
    '''

Generating boarding pass item

AirlineBoardingPass.boarding_pass_item(passenger_name, 
                    logo_image_url, # URL for the airline logo image
                    pnr_number, # Booking nubmer
                    qr_code, # QR code image URL
                    barcode_image_url, # URL of the barcode image
                    above_bar_code_image_url, # URL of thin image above the barcode
                    travel_class, # Must be 'economy', 'business' or 'first_class'
                    flight_info, # flight info object
                    header_image_url="", # URL for the header image
                    header_text_field="", # Text for the header field
                    seat="", # 	Seat number
                    auxiliary_fields="", # Additional information to display in the auxiliary section
                    secondary_fields="") # Additional information to display in the secondary section
    # @output: boarding_pass JSON item

Creating "flight schedule" object

AirlineBoardingPass.make_flight_schedule(departure_time, arrival_time="", boarding_time="")
    '''
    @required
        departure_time
    @optional
        arrival_time
        boarding_time
    @output:
        Flight schedule JSON object
    '''

Generating "flight schedule" item

AirlineBoardingPass.flight_schedule(departure_time, arrival_time, boarding_time="")
    '''
    @required:
        departure_time
        arrival_time
    @optional:
        boarding_time
    @output:
        flight schedule JSON object
    '''

Creating "flight info" item

AirlineBoardingPass.flight_info(flight_number, departure_airport, arrival_airport, flight_schedule, aircraft_type="")
    '''
    @required:
        flight_number
        departure_airport
        arrival_airport
        flight_schedule - flight schedule JSON object (checkout AirlineBoardingPass.flight_schedule)
    @optional:
        aircraft_type
    @output:
        flight info JSON objet
    '''

Creating item with airport details

AirlineBoardingPass.airport(airport_code, city, terminal="", gate="")
   '''
   @required:
       airport_code
       city
   @optional:
       terminal
       gate
   @output:
       JSON object with airport details
   '''

Creating field with label and value

AirlineBoardingPass.field(label, value)
    '''
    @required:
        label
        value
    @output:
        JSON object { "label": label, "value": value }
    '''

Generating payload

 AirlineBoardingPass.get_payload(self)
    '''
    @output:
        payload
    '''

Airline Itinerary template

Go to: Contents

Description at Facebook Developers

message = AirlineItinerary(
    "tickettohell",
    "en_US",
    "EF52A",
    [
        AirlineItinerary.passenger_info_item("Mary","2472784","549"),
        AirlineItinerary.passenger_info_item("John","2472786","550")
    ],
    [
        AirlineItinerary.flight_info_item(
            "cg001",
            "c411",
            "QR142",
            AirlineFlightUpdate.make_airport("SIN","Singapore"),
            AirlineFlightUpdate.make_airport("DME","Moscow"),
            AirlineFlightUpdate.make_flight_schedule("2016-01-05T15:35","2016-01-05T19:35"),
            "econome",
            "Aerobus 500"
        ),
        AirlineItinerary.flight_info_item(
            "cg002",
            "c412",
            "QR142",
            AirlineFlightUpdate.make_airport("DME","Moscow"),
            AirlineFlightUpdate.make_airport("JFK","New York"),
            AirlineFlightUpdate.make_flight_schedule("2016-01-05T20:00","2016-01-06T05:35"),
            "econome",
            "Aerobus 500"
        )

    ],
    [
        AirlineItinerary.passenger_segment_info_item(
            "c411",
            "2472784",
            "D14",
            "Standard",
            [
                AirlineItinerary.product_info_item("Luggage","50kg")
            ]
        ),
        AirlineItinerary.passenger_segment_info_item(
            "c412",
            "2472784",
            "D14",
            "Standard",
            [
                AirlineItinerary.product_info_item("Luggage","30kg")
            ]
        ),
        AirlineItinerary.passenger_segment_info_item(
            "c411",
            "2472786",
            "D16",
            "Standard",
            [
                AirlineItinerary.product_info_item("Luggage","50kg")
            ]
        ),
        AirlineItinerary.passenger_segment_info_item(
            "c412",
            "2472786",
            "D16",
            "Standard",
            [
                AirlineItinerary.product_info_item("Knive-box","3kg")
            ]
        )
    ],
    "500",
    "EUR",
    base_price="430",
    tax="70",
    price_info=[
        AirlineItinerary.price_info_item("Standart price","400","EUR"),
        AirlineItinerary.price_info_item("Service1","15","EUR"),
        AirlineItinerary.price_info_item("Service2","15","EUR")
    ],
)
bot.send_message_TypeC(sender, message)

Airline itinerary example Airline itinerary example

AirlineItinerary class reference

Go to: Contents

Constructor

AirlineItinerary.__init__(self, 
            intro_message, 
            locale, # must be a two-letter ISO 639-1 language code and a ISO 3166-1 alpha-2 region code. e.g. en_US, ru_RU
            pnr_number, # Booking number
            passenger_info, # Array of items generated by AirlineItinenrary.passenger_info_item
            flight_info, # Array of items generated by AirlineItinerary.flight_info_item
            passenger_segment_info, #  Array of items generated by AirlineItinerary.passenger_segment_info_item
            total_price, 
            currency, #  Must be a three digit ISO-4217-3 code - 'USD', 'EUR'...
            theme_color="", #  RGB hexadecimal string (default #009ddc)
            price_info="", # Array of items generated by AirlineItinerary.price_info_item
            base_price="", 
            tax="")

Passenger info item

AirlineItinenrary.passenger_info_item(name, passenger_id,ticket_number="") 
    '''
    @required:
        name - passenger name
        passenger_id
    @optional:
        ticket_number
    @output:
        passenger info JSON object
    '''

Flight info item

AirlineItinerary.flight_info_item(connection_id, 
            segment_id, # 	segment_id of passenger_segment_info object
            flight_number, 
            departure_airport, # airport item
            arrival_airport, # airport item
            flight_schedule, 
            travel_class, # Must be 'economy', 'business' or 'first_class'
            aircraft_type="")

Airport item

AirlineFlightUpdate.airport(airport_code, city, terminal="", gate="")
    '''
    @required:
        airport_code
        city
    @optional:
        terminal
        gate
    @output:
        Airport info JSON object
    '''

Flight schedule object

AirlineItinerary.make_flight_schedule(departure_time, arrival_time, boarding_time="")
    '''
    @required:
        departure_time
        arrival_time
    @optional
        boarding_time
    @output:
        Flight schedule JSON object
    '''

Passenger segment information item

AirlineItinerary.passenger_segment_info_item(segment_id, passenger_id, seat, seat_type, product_info)
    '''
    @required:
        segment_id
        passenger_id
        seat
        seat_type
        product_info
    @output:
        JSON object - passenger segment information
    '''

Product information item

AirlineItinerary.product_info_item(title, value)
    '''
    @required:
        label
        value
    @output:
        Product information item - JSON object { "label": label, "value": value }
    '''

Price information item

AirlineItinerary.price_info_item(title, amount, currency="")
    '''
    @required:
        title
        amount
    @optional:
        currency - USD by default?
    @output:
        Price information item - JSON object

Generating payload

AirlineItinerary.get_payload(self)

Receipt template

Go to: Contents

Description at Facebook Developers

 message = FBOrder(
     "Stephane Crozatier",
     "125352345",
     "USD",
     "Visa",
     [
         FBOrder.one_purchase("T-Shirt", 1,"yellow", 5, "USD", "http://cdn01.shopclues.net/images/detailed/19936/yellowtshirt_1434534567.jpg"),
         FBOrder.one_purchase("Baseball cap", 2,"white",  2, "USD", "http://i01.i.aliimg.com/img/pb/630/860/383/383860630_626.jpg")
     ],
     FBOrder.price_summary(9, 0, 1, 8),
     "http://google.com",
     FBOrder.address("1 Hacker Way", "", "Menlo Park", "94025", "CA", "US"),
     "427561765",
     [
         FBOrder.price_one_adjustment("2$ Off coupon", 2)
     ]
 )
 bot.send_message_TypeC(sender, message)

FBOrder example pic FBOrder example pic

FBOrder class reference (Receipt template)

Go to: Contents

 
# Constructor  
FBOrder.__init__(self,
                recipient_name,  
                order_number,
                currency,
                payment_method,
                purchases_array,
                price_summary,
                order_url="",
                address="",
                timestamp="",
                price_adjustments_array="",
                **kwargs)
 
# Creates purchase JSON object
FBOrder.one_purchase(title,  price, subtitle="", quantity="",currency="", image_url="")
    '''
    @required:
        title  
        price
    @optional:
        subtitle
        quantity
        currency
        image_url
    '''
 
# Creates adress JSON object
FBOrder.address(street1, street2, city, postal_code, state, country)
    '''
    @required:
        street1
        street2
        city
        postal_code
        state
        country
    '''
 
# Creates summary JSON object
FBOrder.price_summary(subtotal, shipping_cost, total_tax, total_cost)
    '''
    @required:
        subtotal
        shipping_cost
        total_tax
        total_cost
    '''
 
# Creates price JSON object
FBOrder.price_one_adjustment(name, amount)
    '''
    @required:
        name
        amount
    '''
 
# Creates payload JSON object
FBOrder.get_payload(self)
 
 

FBBot class reference

Go to: Contents

# Constructor
FBBot.__init__(self, access_token, verify_token, **kwargs)
    '''
    @required:
        access_token
        verify_token
    @optional:
        api_version
        app_secret
    '''

# Receives information about user by id
FBBot.get_userinfo(self, user_id)
    '''
    @required:
        user_id
    '''

# 
FBBot.webhook(self, request, on_message_received, on_postback_received, on_account_linked="", on_account_unlinked="")
    '''
    @required:
        request
        on_message_received(sender_id, message_text, requestInfo)
        on_postback_received(sender_id, postback_text, requestInfo)
    @output:
        htmlView
    '''

# Sets bot greeting text for new users
FBBot.set_greeting_text(self, greeting_text)
    '''
    @required:
        greeting_text
    '''

# Sets the button that will be shown for new users
FBBot.set_get_started_button(self, postback_text)
    '''
    @required:
        postback_text
    @output
        response JSON
    '''

# Deletes "get started" button
FBBot.delete_get_started_button(self)

# Creates persistent menu with buttons
FBBot.set_persistent_menu(self, buttons):
    '''
    @required:
        buttons array, up to 5 buttons, each is FBAttachment.button
    @output:
        response_json
    '''
        
# Deletes persistent menu and returns response JSON
FBBot.delete_persistent_menu(self)

# Sends text message to recipient
FBBot.send_text_message(self, recipient_id, text, quick_replies = []) 
    '''
    @required:
        recipient_id
        text
    @optional:
        quick_replies array, up to ten replies, each is FBAttachment.quick_reply
    @output:
        response_json
    '''

# Sends message with file attachment to recipient
FBBot.send_message_file_attachment(self, recipient_id, attachment_type, file_url, quick_replies = [])
    '''
    @required:
        recipient_id
        attachment_type from FBAttachment.File
        file_url
    @optional:
        quick_replies array, up to ten replies, each is FBAttachment.quick_reply
    @output:
        response_json
    '''

# Sends generic message with image and buttons to recipient 
FBBot.send_message_generic(self, recipient_id, title, subtitle, image_url, buttons = [], quick_replies = [])
    '''
    @required:
        recipient_id
        title
        subtitle (may be empty string)
        image_url (may be empty string)
    @optional:
        buttons array, up to three buttons, each is FBAttachment.button
        quick_replies array, up to ten replies, each is FBAttachment.quick_reply
    @output:
        response_json
    '''
   
# Sends template message to recipient
FBBot.send_message_TypeC(self, recipient_id, template, quick_replies = [])
    '''
    @required:
        recipient_id
        template is instance of FBOrder or AirlineChekin or AirlineFlightUpdate (Facebook templates)
    @optional:
        quick_replies array, up to ten replies, each is FBAttachment.quick_reply
    @output:
        response_json
    '''

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Python 100.0%