Facebook Messenger Webhook

Facebook Messenger webhook middleware for Express.

Installation

$ npm install fbm-webhook

Usage

Add fbm-webhook middleware into your existing Express app:

const express = require("express");
const fbmWebhook = require("fbm-webhook");

const app = express();
const webhook = fbmWebhook({
  appSecret: "Your Facebook App Secret",
  verifyToken: "Your Predefined Verify Token"
});

app.use("/webhook", webhook);

// Listen to the message received event.
webhook.on("message", event => {
  console.log(`Sender id: ${event.sender.id}`);
  console.log(`Message: ${event.message}`);
});

// Listen to the message read event.
webhook.on("read", event => console.log(event));

app.listen(3000, () => console.log("Server is running on port: 3000"));

The fbm-webhook middleware will register two endpoints:

• GET /webhook: For webhook URL verification.
• POST /webhook: The actual webhook that will receive events data from the Facebook Messenger.

The verifyToken is your own predefined secret. It's the one that will be used by Facebook to verify your webhook URL.

Check all supported webhook events.

Recipes

Store App Secret and Verify Token as Environment Variables

By default, fbm-webhook will look for FB_APP_SECRET and FB_VERIFY_TOKEN on the environment variables. If you set these environment variable, you don't have to pass anything:

const fbmWebhook = require("fbm-webhook");

const webhook = fbmWebhook();

// Is equal to
const webhook = fbmWebhook({
  appSecret = process.env.FB_APP_SECRET,
  verifyToken = process.env.FB_VERIFY_TOKEN
});

And if you use another name:

const fbmWebhook = require("fbm-webhook");

const webhook = fbmWebhook({
  appSecret = process.env.MY_APP_SECRET,
  verifyToken: process.env.MY_VERIFY_TOKEN
});

Use Different Endpoints

const express = require("express");
const fbmWebhook = require("fbm-webhook");

const app = express();
const webhook = fbmWebhook();

app.use("/foobar", webhook);

Your webhook endpoints will be:

• GET /foobar: For webhook verification.
• POST /foobar: The actual webhook handler.

Listen to All Types of Event

const express = require("express");
const fbmWebhook = require("fbm-webhook");

const app = express();
const webhook = fbmWebhook();

app.use("/webhook", webhook);

// Listen to all types of event.
webhook.on("data", event => console.log(event));

app.listen(3000, () => console.log("Server is running on port: 3000"));

Disable Request Signature Verification

By default, fbm-webhook will look for the X-Hub-Signature header on all incoming webhook. It will verify this request signature using your appSecret. You can disable this verification process by passing a false value to appSecret (it's not recommended though).

const fbmWebhook = require("fbm-webhook");

const webhook = fbmWebhook({ appSecret: false });

Run as Standalone Express Application

You can instantiate fbm-webhook as an Express application too:

const fbmWebhook = require("fbm-webhook");

const webhook = fbmWebhook({ path: "/webhook" });

// Listen to the message received event.
webhook.on("message", event => {
  console.log(`Sender id: ${event.sender.id}`);
  console.log(`Message: ${event.message}`);
});

webhook.listen(3000, () => console.log("Server is running on port: 3000"));

Webhook Events

Event Type	Messenger Subscription Field	Documentation
message	messages	Message recevied events
echo	message_echoes	Message Echo events
account-linking	messaging_account_linking	Account Linking events
checkout-update	messaging_checkout_updates	Checkout Update events
delivered	message_deliveries	Message Delivered events
game-play	messaging_game_plays	Instant Game events
optin	messaging_optins	Plugin Opt-in events
payment	messaging_payments	Payment events
policy-enforcement	messaging_policy_enforcement	Policy Enforcement events
postback	messaging_postbacks	Postback Received events
pre-checkout	messaging_pre_checkouts	Payment Pre-checkout events
read	message_reads	Message Read events
referral	messaging_referrals	Referral events
standby	standby	Handover Protocol Standby Channel events
handover.app-roles	messaging_handovers	Handover Protocol assign app roles events
handover.pass-thread-control	messaging_handovers	Handover Protocol pass thread control events
handover.take-thread-control	messaging_handovers	Handover Protocol take thread control events
handover.request-thread-control	messaging_handovers	Handover Protocol request thread control events
unknown		Other event types not listed above
data		Listen to all type of events

API

fbmWebhook

fbmWebhook([{
  path = "/",
  appSecret = process.env.FB_APP_SECRET,
  verifyToken = process.env.FB_VERIFY_TOKEN
}])

Parameters

• path (optional String): The webhook route prefix, default to /.
• appSecret (optional String): Your Facebook App Secret, default to process.env.FB_APP_SECRET.
• verifyToken (optional String): Your own predefined verify token. Used by Facebook to verify webhook URL, default to process.env.FB_VERIFY_TOKEN.

Return

It returns an Express application instance.

fbmWebhook.on

Listen to a webhook event.

fbmWebhook.on(eventType, callback);

Parameters

• eventType (String): The webhook event to listen to.
• callback (Function): The callback function to call, it will receive the event payload sent by the Messenger platform.

Related

• fbm-send: Module for sending message through Facebook Messenger Send API.

License

MIT © Risan Bagja Pradana

Legal

This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by Facebook or any of its affiliates or subsidiaries. This is an independent and unofficial API.