FB Bot Framework
fb-bot-framework
is a node framework for Facebook Messenger Platform(FB Messenger Bot).
Installation
npm install fb-bot-framework --save
Features
- work as Express Middleware
- implement of Send API.
- customize notification type(REGULAR, SILENT_PUSH, NO_PUSH) for each individual message
- implement of Thread Settings API (Greeting Text / Get Started Button / Persistent Menu)
Example Usage
You can use bot.middleware()
to hook any request to the path /webhook
to the bot.
var express = ;var app = ; var FBBotFramework = ; // Initializevar bot = page_token: "THIS_IS_PAGE_TOKEN" verify_token: "THIS_IS_VERIFY_TOKEN"; // Setup Express middleware for /webhookapp; // Setup listener for incoming messagesbot; // Setup listener for quick reply messagesbot; // Config the Get Started Button and register a callbackbot;bot; { // Get started process } // Setup listener for attachmentbot; // Make Express listeningapp;
API
Events
bot.on("message", function(userId, message))
Triggered when an user sends a typed message to the bot.
userId
- String: The Facebook Id of the sender.message
- String: The actual message sent by the user.
bot.on("postback", function(userId, payload))
Triggered when an user clicks a button which will send a postback message.
userId
- String: The Facebook Id of the sender.payload
- String: The payload associated with the button clicked by the user.
bot.on("quickreply", function(userId, payload))
Triggered when an user clicks a quick reply button..
userId
- String: The Facebook Id of the sender.payload
- String: The payload associated with the button clicked by the user.
Functions
bot.setGreetingText(text, cb)
Set the greeting message for new conversations.
text
- The greeting textcb
- Optional, callback with arguments oferr
andresult
.
bot.setGetStartedButton(payload, cb)
Set the Get Started button postback callback in the Welcome Screen.
payload
- The postback callback to be calledcb
- Optional, callback with arguments oferr
andresult
.
bot.setPersistentMenu(menuButtons, cb)
Set the Persistent Menu which is always available to the user.
menuButtons
- The menu button for the Persistent Menucb
- Optional, callback with arguments oferr
andresult
.
var menuButtons = "type": "postback" "title": "Help" "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_HELP" "type": "postback" "title": "Start a New Order" "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_START_ORDER" "type": "web_url" "title": "View Website" "url": "http://petersapparel.parseapp.com/" ;bot;
bot.sendTextMessage(userId, text, notificationType, cb)
Send a text message to a specific user.
userId
- The recipient's Facebook Idtext
- The actual textnotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
bot.sendImageMessage(userId, imageUrl, notificationType, cb)
Send an image message to a specific user.
userId
- The recipient's Facebook IdimageUrl
- The url of the imagenotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
bot.sendAudioAttachment(userId, audioUrl, notificationType, cb)
Send an image message to a specific user.
userId
- The recipient's Facebook IdaudioUrl
- The url of the audio filenotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
bot.sendVideoAttachment(userId, videoUrl, notificationType, cb)
Send an image message to a specific user.
userId
- The recipient's Facebook IdvideoUrl
- The url of the video filenotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
bot.sendFileAttachment(userId, fileUrl, notificationType, cb)
Send an image message to a specific user.
userId
- The recipient's Facebook IdfileUrl
- The url of the filenotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
bot.sendButtonMessage(userId, text, buttons, notificationType, cb)
Send a message with buttons to a specific user.
userId
- The recipient's Facebook Idtext
- The title of the messagebuttons
- The buttons of the messagenotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
var text = "What do you want to do next?";var buttons = "type": "web_url" "url": "https://petersapparel.parseapp.com" "title": "Show Website" "type": "postback" "title": "Start Chatting" "payload": "USER_DEFINED_PAYLOAD" ;bot;
bot.sendGenericMessage(userId, elements, notificationType, cb)
Send a message with bubbles(horizontal scroll cards) to a specific user.
userId
- The recipient's Facebook Idelements
- The elements of the messagenotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
var elements = "title": "Classic White T-Shirt" "image_url": "http://petersapparel.parseapp.com/img/item100-thumb.png" "subtitle": "Soft white cotton t-shirt is back in style" "buttons": "type": "web_url" "url": "https://petersapparel.parseapp.com/view_item?item_id=100" "title": "View Item" "type": "web_url" "url": "https://petersapparel.parseapp.com/buy_item?item_id=100" "title": "Buy Item" "type": "postback" "title": "Bookmark Item" "payload": "USER_DEFINED_PAYLOAD_FOR_ITEM100" "title": "Classic Grey T-Shirt" "image_url": "http://petersapparel.parseapp.com/img/item101-thumb.png" "subtitle": "Soft gray cotton t-shirt is back in style" "buttons": "type": "web_url" "url": "https://petersapparel.parseapp.com/view_item?item_id=101" "title": "View Item" "type": "web_url" "url": "https://petersapparel.parseapp.com/buy_item?item_id=101" "title": "Buy Item" "type": "postback" "title": "Bookmark Item" "payload": "USER_DEFINED_PAYLOAD_FOR_ITEM101" ; bot;
bot.sendBubbleMessage(userId, elements, notificationType, cb)
It is the same as sendGenericMessage()
bot.sendReceiptMessage(userId, receipt, notificationType, cb)
Send a message with receipt to a specific user.
userId
- The recipient's Facebook Idelements
- The elements of the messagenotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
var receipt = "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" "elements": "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" "title": "Classic Gray T-Shirt" "subtitle": "100% Soft and Luxurious Cotton" "quantity": 1 "price": 25 "currency": "USD" "image_url": "http://petersapparel.parseapp.com/img/grayshirt.png" "address": "street_1": "1 Hacker Way" "street_2": "" "city": "Menlo Park" "postal_code": "94025" "state": "CA" "country": "US" "summary": "subtotal": 7500 "shipping_cost": 495 "total_tax": 619 "total_cost": 5614 "adjustments": "name": "New Customer Discount" "amount": 20 "name": "$10 Off Coupon" "amount": 10 ; bot;
bot.sendLocationRequest(userId, text, notificationType, cb)
Send a location request message to a specific user.
userId
- The recipient's Facebook Idtext
- The prompt text ask for locationnotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
bot.sendQuickReplies(userId, text, replies, notificationType, cb)
Send quick reply message to a specific user.
userId
- The recipient's Facebook Idtext
- The title of the messagereplies
- The quick reply buttonsnotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Optional, callback with arguments oferr
andresult
.
var replies = "content_type": "text" "title": "Good" "payload": "thumbs_up" "content_type": "text" "title": "Bad" "payload": "thumbs_down" ;bot; bot;
bot.sendListMessage(userId, elements, notificationType, cb)
Send quick reply message to a specific user.
userId
- The recipient's Facebook Idelements
- The list elements of the messagenotificationType
- Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSHcb
- Op
var elements = "title": "Classic T-Shirt Collection" "image_url": "https://peterssendreceiveapp.ngrok.io/img/collection.png" "subtitle": "See all our colors" "default_action": "type": "web_url" "url": "https://peterssendreceiveapp.ngrok.io/shop_collection" "messenger_extensions": true "webview_height_ratio": "tall" "fallback_url": "https://peterssendreceiveapp.ngrok.io/" "buttons": "title": "View" "type": "web_url" "url": "https://peterssendreceiveapp.ngrok.io/collection" "messenger_extensions": true "webview_height_ratio": "tall" "fallback_url": "https://peterssendreceiveapp.ngrok.io/" "title": "Classic White T-Shirt" "image_url": "https://peterssendreceiveapp.ngrok.io/img/white-t-shirt.png" "subtitle": "100% Cotton, 200% Comfortable" "default_action": "type": "web_url" "url": "https://peterssendreceiveapp.ngrok.io/view?item=100" "messenger_extensions": true "webview_height_ratio": "tall" "fallback_url": "https://peterssendreceiveapp.ngrok.io/" "buttons": "title": "Shop Now" "type": "web_url" "url": "https://peterssendreceiveapp.ngrok.io/shop?item=100" "messenger_extensions": true "webview_height_ratio": "tall" "fallback_url": "https://peterssendreceiveapp.ngrok.io/" "title": "Classic Blue T-Shirt" "image_url": "https://peterssendreceiveapp.ngrok.io/img/blue-t-shirt.png" "subtitle": "100% Cotton, 200% Comfortable" "default_action": "type": "web_url" "url": "https://peterssendreceiveapp.ngrok.io/view?item=101" "messenger_extensions": true "webview_height_ratio": "tall" "fallback_url": "https://peterssendreceiveapp.ngrok.io/" "buttons": "title": "Shop Now" "type": "web_url" "url": "https://peterssendreceiveapp.ngrok.io/shop?item=101" "messenger_extensions": true "webview_height_ratio": "tall" "fallback_url": "https://peterssendreceiveapp.ngrok.io/" "title": "Classic Black T-Shirt" "image_url": "https://peterssendreceiveapp.ngrok.io/img/black-t-shirt.png" "subtitle": "100% Cotton, 200% Comfortable" "default_action": "type": "web_url" "url": "https://peterssendreceiveapp.ngrok.io/view?item=102" "messenger_extensions": true "webview_height_ratio": "tall" "fallback_url": "https://peterssendreceiveapp.ngrok.io/" "buttons": "title": "Shop Now" "type": "web_url" "url": "https://peterssendreceiveapp.ngrok.io/shop?item=102" "messenger_extensions": true "webview_height_ratio": "tall" "fallback_url": "https://peterssendreceiveapp.ngrok.io/" ;bot;
bot.getUserProfile(userId, cb)
Get the Facebook profile from a specific user.
userId
- The target's Facebook Idcb
- callback with arguments oferr
andprofile
.
bot;