fb-messenger-sdk

NodeJS Facebook Messenger API

Installation

npm install fb-messenger-sdk

Table of Contents

• Documentation
• Features
• Setup
• Sending Messages
  • Text Message
  • Image Message
  • Buttons Message
  • Quick Reply Message
  • Generic Template List ( Horizontal Scroll List)
  • List Message ( Vertical Scroll List)
  • Mark as Seen
  • Toggle Writing Bubble
  • User Profile
• Incoming Message Parser
• Setting Messenger Profile
  • Setting Greeting Message
  • Setting Get Started Button
  • Setting Persistent Menu
• Sending Facebook Page Posts
  • Page Image Posts
  • Page Link Posts
• Validating Facebook Webhook
  • Server Validation
  • Lambda Validation
• Validating Message Integrity
• Complete Examples
• Creating Facebook App

Features

• Near complete Typescript types for all incoming/outgoing Facebook Messaging API payloads & webhooks
• Builders for all types of buttons/templates
• Incoming Message Parser & Extractor
• Webhook Validation logic
• Page posting
• Profile interactions
• Promises and callback support on all functions, if no callback provided, promise returned, allows you to manage flow as you desire AND to ensure message ordering
• Supports proxying
• Typescript code with exported types for every end-point input/output
• Custom facebook API version

Setup

Import

const facebook = require('fb-messenger-sdk');

or

import { FacebookMessagingAPIClient, etc... } from 'fb-messenger-sdk';

Sending Messages

Initialize

const messageClient = new facebook.FacebookMessagingAPIClient(process.env.PAGE_ACCESS_TOKEN);

or

const messageClient = new FacebookMessagingAPIClient(process.env.PAGE_ACCESS_TOKEN);

Using proxy

const messageClient = new facebook.FacebookMessagingAPIClient(process.env.PAGE_ACCESS_TOKEN, { hostname:process.env.PROXY_HOST, port: process.env.PROXY_PORT });

or

const messageClient = new FacebookMessagingAPIClient(process.env.PAGE_ACCESS_TOKEN, { hostname:process.env.PROXY_HOST, port: process.env.PROXY_PORT });

Defaults to http if no protocol provided

Text Message

messageClient.sendTextMessage(senderId, <MESSAGE>)
    .then((result) => ...)

or

await messageClient.sentTextMessage(senderId, <MESSAGE>);

Image Message

messageClient.sendImageMessage(senderId, <IMAGE_URL>)
    .then((result) => ...)

or

const result = await messageClient.sendImageMessage(senderId, <IMAGE_URL>)

This method will have the image cached by facebook so every receiver after the first will get it quickly.

Buttons Message

messageClient.sendButtonsMessage(senderId, <BUTTONS TEXT> [<ARRAY OF BUTTONS>])
    .then((result) => ...)

or

const result = await messageClient.sendButtonsMessage(senderId, <BUTTONS TEXT> [<ARRAY OF BUTTONS>])

Buttons format

Quick Reply Message

messageClient.sendQuickReplyMessage(senderId, <TEXT>, [<QUICK_REPLIES>])
    .then((result) => ...)

or

const result = await messageClient.sendQuickReplyMessage(senderId, <TEXT>, [<QUICK_REPLIES>])

Quick Reply format

Generic Template Message ( Horizontal Scroll List )

messageClient.sendGenericTemplate(senderId, [ELEMENTS])
    .then((result) => ...)

or

const result = await messageClient.sendGenericTemplate(senderId, [ELEMENTS])

Generic Template element format

List Message ( Vertical Scroll List )

messageClient.sendListMessage(senderId, [ELEMENTS], <firstElementStyle>, [FINAL_BUTTONS])
    .then((result) => ...)

or

const result = await messageClient.sendListMessage(senderId, [ELEMENTS], <firstElementStyle>, [FINAL_BUTTONS])

firstElementStyle is optional. If not provided defaults to large

List Template element format

Mark as Seen

messageClient.markSeen(senderId);

As per all methods, callback can be provided. If no callback provided returns promise. Recommended to send and continue processing without waiting for reply.

Toggle writing bubble

messageClient.toggleTyping(senderId, <true/false>);

As per all methods, callback can be provided. If no callback provided returns promise. Recommended to send and continue processing without waiting for reply. Defaults to false if no boolean parameter provided.

User Profile

messageClient.getUserProfile(senderId,[<PROPERTIES>])
    .then((result) => ...)

or

const result = await messageClient.getUserProfile(senderId,[<PROPERTIES>])

Valid properties: first_name,last_name,profile_pic,locale,timezone,gender,is_payment_enabled,last_ad_referral If none are given defaults to first_name only.

Incoming Message Parser

Extracts all relevant & known message types that can be found here. Returns array with all objects of interest. Left flexibility to user to filter out message types of interest per use case instead of returning dictionary object with each message type as a separate list for optional performance saving in case of usage on time sensitive platforms (AWS Lambda, AF, GCF, etc).

import {FacebookMessageParser} from 'fb-messenger-sdk';
const messages = FacebookMessageParser.parsePayload(incomingPayload);

Setting Messenger Profile

Initialize

const profileClient = new facebook.FacebookProfileAPIClient(process.env.PAGE_ACCESS_TOKEN);

or

import {Profile} from 'fb-messenger-sdk';
const profileClient = new FacebookProfileAPIClient(process.env.PAGE_ACCESS_TOKEN);

Using proxy

const profileClient = new facebook.FacebookProfileAPIClient(process.env.PAGE_ACCESS_TOKEN, { hostname:process.env.PROXY_HOST, port: process.env.PROXY_PORT });

Setting Greeting Message

profileClient.setGreetingMessage('Message that will be visible first thing when opening chat window with your bot/page')
.then((result) => ...)

or

const result = await profileClient.setGreetingMessage('Message that will be visible first thing when opening chat window with your bot/page');

Setting Get Started button

profileClient.setGetStartedAction(senderId, payload)
    .then((result) => ...)

or

const result = await profileClient.setGetStartedAction(senderId, payload)

payload is the value that will be first sent when new user sends first message, once per user interaction

Setting Persistent Menu

profileClient.setPersistentMenu(senderId, [<MENU_ENTRIES>])
    .then((result) => ...)

or

const result = await profileClient.setPersistentMenu(senderId, [<MENU_ENTRIES>])

This is a burger menu appearing next to the chat input field where users can click and get direct interaction shortcuts to specific functionality of the bot. Persistent menu format

Sending Facebook Page Posts

Initialize

const pageClient = new facebook.FacebookPageAPIClient(process.env.PAGE_ID, process.env.PAGE_ACCESS_TOKEN);

or

import {FacebookPageAPIClient} from 'fb-messenger-sdk';
const pageClient = new FacebookPageAPIClient(process.env.PAGE_ID, process.env.PAGE_ACCESS_TOKEN)

Using proxy

const pageClient = new facebook.FacebookPageAPIClient(process.env.PAGE_ID, process.env.PAGE_ACCESS_TOKEN, { hostname:process.env.PROXY_HOST, port: process.env.PROXY_PORT });

Defaults to http if no protocol provided

Requires a never expiring publishing_actions token that can be obtained by following this guide.

Page Image Posts

pageClient.imageUrl(`<URL>`).imageCaption(`<CAPTION>`).sendImage(`<CALLBACK>`);

<URL> is the url of the image being posted

<CAPTION> is the text you want on top of the image

<CALLBACK> is optional callback otherwise promise is returned

Page Link Posts

pageClient.postUrl(`<URL>`).postMessage(`<MESSAGE>`).sendPost(`<CALLBACK>`);

<URL> is the url of the link being posted

<MESSAGE> is the text you want on top of the link

<CALLBACK> is optional callback otherwise promise is returned

Validating Facebook Webhook

Server Validation

const facebook = require('fb-messenger-sdk');
const router = require('express').Router();
router.get('/api/webhook',(req, res) => facebook.ValidateWebhook.validateServer(req,res));

Example based on usage with Express Router, can use any other middleware which passes in the req and response objects. Assumes verification token set under process.env.FB_VERIFICATION_TOKEN.

Alternatively, if you want to pass in your set token in a different manner or under different name you can use

ValidateWebhook.validateServer(req, res, <TOKEN>);

This allows you to obtain the value as you wish and still use it as above with the help of currying.

...
const validateWebhook = function validateWebhook(token) {
  return (req, res) => facebook.ValidateWebhook.validateServer(req, res, token);
}
const validator = validateWebhook(<TOKEN>);
router.get('/api/webhook/',validator);

Lambda Validation

Alternatively, you can use this when running on AWS Lambda to take advantage of the serverless paradigm as follows:

import {ValidateWebhook} from 'fb-messenger-sdk';
const handler = (event, context, callback: Function) => {
    ...
    if(event.httpMethod === 'GET') {
        ValidateWebhook.validateLambda(event, callback);
    }
    ...
}

Both validateLambda and validateServer support passing in verification token as third parameter. Otherwise will check process.env.FB_VERIFICATION_TOKEN for value.

Validating Message Integrity

Validates the integrity of the message received from Facebook platform using the provided signature signed with Facebook Application Secret.

The Facebook application secret can be provided either as second optional parameter to ValidateWebhook.validateMessageIntegrity(<X-HUB-SIGNATURE>, <FB_APPLICATION_SECRET>) or by setting process.env.FB_APPLICATION_SECRET.

Compatible with both server/less paradigms as part of single line middleware function to Express or as Lambda first check before callback or remainder or programme.

import {ValidateWebhook} from 'fb-messenger-sdk';
const messageIntegrityChecker = (req, res) => {
    const validMessage = ValidateWebhook.validateMessageIntegrity(req.headers["x-hub-signature"]);
    ...
}
router.post('/api/webhook/',messageIntegrityChecker);

Complete example

const router = require('express').Router();
const facebook = require('fb-messenger-sdk');
const messagingClient = new facebook.FacebookMessagingAPIClient(process.env.PAGE_ACCESS_TOKEN);
const messageParser = facebook.FacebookMessageParser;
...
router.get('/api/webhook',facebook.ValidateWebhook.validateServer);
router.post('/api/webhook', (req, res) => {
    const incomingMessages = messageParser.parsePayload(req.body);  
    ...
    messagingClient.markSeen(senderId)
        .then(() => client.toggleTyping(senderId,true))
        .catch((err) => console.log(error));
    ...
    //promise based reaction on message send confirmation
    messagingClient.sendTextMessage(senderId, 'Hello')
        .then((result) => console.log(`Result sent with: ${result}`));
    ...
    //callback based reaction on message confirmation
    messagingClient.sendTextMessage(senderId, 'Hello',(result) => console.log(`Result sent with: ${result}`));
    ...
    //silent message sending
    messagingClient.sendTextMessage(senderId,'Hello');
})

or

import {FacebookMessagingAPIClient, ValidateWebhook, FacebookMessageParser} from 'fb-messenger-sdk';
import {Router} from 'express';
...
router.get('/api/webhook',facebook.ValidateWebhook.validateServer);
router.post('/api/webhook', (req, res) => {
    try {
    const incomingMessages = messageParser.parsePayload(req.body);  
        ...
        await messagingClient.markSeen(senderId);
        await messagingClient.toggleTyping(senderId,true));
        ...
        //promise based reaction on message send confirmation
        const result = await messagingClient.sendTextMessage(senderId, 'Hello');
        console.log(`Result sent with: ${result}`));
        ...
    } catch(e){...}
    //callback based reaction on message confirmation
    messagingClient.sendTextMessage(senderId, 'Hello',(result) => console.log(`Result sent with: ${result}`));
    ...
    //silent message sending
    messagingClient.sendTextMessage(senderId,'Hello');
});

Creating Facebook app

See Facebook Guide