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 = require('express');
var app = express();

var FBBotFramework = require('fb-bot-framework');

// Initialize
var bot = new FBBotFramework({
	page_token: "THIS_IS_PAGE_TOKEN",
    verify_token: "THIS_IS_VERIFY_TOKEN"
});

// Setup Express middleware for /webhook
app.use('/webhook', bot.middleware());

// Setup listener for incoming messages
bot.on('message', function(userId, message){
    // bot.sendTextMessage(userId, "Echo Message:" + message);
	
    // Send quick replies
    var replies = [
        {
            "content_type": "text",
            "title": "Good",
            "payload": "thumbs_up"
        },
        {
            "content_type": "text",
            "title": "Bad",
            "payload": "thumbs_down"
        }
    ];
    bot.sendQuickReplies(userId, message, replies);
});

// Setup listener for quick reply messages
bot.on('quickreply', function(userId, payload){
	bot.sendTextMessage(userId, "payload:" + payload);
});

// Config the Get Started Button and register a callback
bot.setGetStartedButton("GET_STARTED");
bot.on('postback', function(userId, payload){

    if (payload == "GET_STARTED") {
        getStarted(userId);
    }
    
    // Other postback callbacks here
    // ...
    
});

function getStarted(userId){
    
    // Get started process 
}

// Setup listener for attachment
bot.on('attachment', function(userId, attachment){
    
    // Echo the audio attachment
    if (attachment[0].type == "audio") {
        bot.sendAudioAttachment(userId, attachment[0].payload.url);
    }
    
});

// Make Express listening
app.listen(3000);

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 text
• cb - Optional, callback with arguments of err and result.

bot.setGetStartedButton(payload, cb)

Set the Get Started button postback callback in the Welcome Screen.

• payload - The postback callback to be called
• cb - Optional, callback with arguments of err and result.

bot.setPersistentMenu(menuButtons, cb)

Set the Persistent Menu which is always available to the user.

• menuButtons - The menu button for the Persistent Menu
• cb - Optional, callback with arguments of err and result.

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.setPersistentMenu(menuButtons);

bot.sendTextMessage(userId, text, notificationType, cb)

Send a text message to a specific user.

• userId - The recipient's Facebook Id
• text - The actual text
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

bot.sendImageMessage(userId, imageUrl, notificationType, cb)

Send an image message to a specific user.

• userId - The recipient's Facebook Id
• imageUrl - The url of the image
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

bot.sendAudioAttachment(userId, audioUrl, notificationType, cb)

Send an image message to a specific user.

• userId - The recipient's Facebook Id
• audioUrl - The url of the audio file
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

bot.sendVideoAttachment(userId, videoUrl, notificationType, cb)

Send an image message to a specific user.

• userId - The recipient's Facebook Id
• videoUrl - The url of the video file
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

bot.sendFileAttachment(userId, fileUrl, notificationType, cb)

Send an image message to a specific user.

• userId - The recipient's Facebook Id
• fileUrl - The url of the file
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

bot.sendButtonMessage(userId, text, buttons, notificationType, cb)

Send a message with buttons to a specific user.

• userId - The recipient's Facebook Id
• text - The title of the message
• buttons - The buttons of the message
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

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.sendButtonMessage(recipient, text, buttons);

bot.sendGenericMessage(userId, elements, notificationType, cb)

Send a message with bubbles(horizontal scroll cards) to a specific user.

• userId - The recipient's Facebook Id
• elements - The elements of the message
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

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.sendGenericMessage(recipient, elements, buttons);

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 Id
• elements - The elements of the message
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

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": 75.00,
        "shipping_cost": 4.95,
        "total_tax": 6.19,
        "total_cost": 56.14
    },
    "adjustments": [
        {
            "name": "New Customer Discount",
            "amount": 20
        },
        {
            "name": "$10 Off Coupon",
            "amount": 10
        }
    ]
};

bot.sendReceiptMessage(recipient, receipt);

bot.sendLocationRequest(userId, text, notificationType, cb)

Send a location request message to a specific user.

• userId - The recipient's Facebook Id
• text - The prompt text ask for location
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

bot.sendQuickReplies(userId, text, replies, notificationType, cb)

Send quick reply message to a specific user.

• userId - The recipient's Facebook Id
• text - The title of the message
• replies - The quick reply buttons
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - Optional, callback with arguments of err and result.

var replies = [
    {
        "content_type": "text",
        "title": "Good",
        "payload": "thumbs_up"
    },
    {
        "content_type": "text",
        "title": "Bad",
        "payload": "thumbs_down"
    }
];
bot.sendQuickReplies(userId, message, replies);

bot.on('quickreply', function (userId, payload) {
    console.log("payload =" + payload);
});

bot.sendListMessage(userId, elements, notificationType, cb)

Send quick reply message to a specific user.

• userId - The recipient's Facebook Id
• elements - The list elements of the message
• notificationType - Optional, push notification type: REGULAR (default), SILENT_PUSH, NO_PUSH
• cb - 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.sendListMessage(userId, elements);

bot.getUserProfile(userId, cb)

Get the Facebook profile from a specific user.

• userId - The target's Facebook Id
• cb - callback with arguments of err and profile.

bot.getUserProfile(userId, function (err, profile) {
    console.log(profile);
});