fb-messenger-bot-api
NodeJS Facebook Messenger API
Installation
npm install fb-messenger-bot-api
Table of Contents
- Documentation
- Features
- Setup
- Sending Messages
- Incoming Message Parser
- Setting Messenger Profile
- Sending Facebook Page Posts
- Validating Facebook Webhook
- Validating Message Integrity
- Complete Examples
- Creating Facebook App
Documentation
You can find documentation here
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
- Using latest Facebook API v3.1
Setup
Import
const facebook = ;
or
;
Sending Messages
Initialize
const messageClient = processenvPAGE_ACCESS_TOKEN;
or
;
Using proxy
const messageClient = processenvPAGE_ACCESS_TOKEN hostname:processenvPROXY_HOST port: processenvPROXY_PORT ;
or
;
Defaults to http
if no protocol provided
Text Message
messageClient
or
await messageClient.sentTextMessagesenderId, MESSAGE;
Image Message
messageClient
or
This method will have the image cached by facebook so every receiver after the first will get it quickly.
Buttons Message
messageClient
or
Quick Reply Message
messageClient
or
Generic Template Message ( Horizontal Scroll List )
messageClient
or
Generic Template element format
List Message ( Vertical Scroll List )
messageClient
or
firstElementStyle
is optional. If not provided defaults to large
Mark as Seen
messageClient;
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;
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
or
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).
;;
Setting Messenger Profile
Initialize
const profileClient = processenvPAGE_ACCESS_TOKEN;
or
;;
Using proxy
const profileClient = processenvPAGE_ACCESS_TOKEN hostname:processenvPROXY_HOST port: processenvPROXY_PORT ;
Setting Greeting Message
profileClient
or
;
Setting Get Started button
profileClient
or
payload
is the value that will be first sent when new user sends first message, once per user interaction
Setting Persistent Menu
profileClient
or
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 = processenvPAGE_ID processenvPAGE_ACCESS_TOKEN;
or
;
Using proxy
const pageClient = processenvPAGE_ID processenvPAGE_ACCESS_TOKEN hostname:processenvPROXY_HOST port: processenvPROXY_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;
<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;
<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 = ;const router = ;router;
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;
This allows you to obtain the value as you wish and still use it as above with the help of currying.
...const validateWebhook = { return facebookValidateWebhook;}const validator = ;router;
Lambda Validation
Alternatively, you can use this when running on AWS Lambda to take advantage of the serverless paradigm as follows:
;
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.
;router.post'/api/webhook/',messageIntegrityChecker;
Complete example
const router = ;const facebook = ;const messagingClient = processenvPAGE_ACCESS_TOKEN;const messageParser = facebookFacebookMessageParser;...router;router
or
;;...router.get'/api/webhook',facebook.ValidateWebhook.validateServer;router.post'/api/webhook',;