fb.me

This is an Expressexpressjs-url app for chatbot development on Facebook Messenger that uses Facebook Messenger API, specifically the Send APIsend-api-url by providing a set of methods and route handlers to better deal with a few common tasks while developing any kind of typical chatbot:

Table of contents

• Pre-requisites
• Setup

- [Node.js](#nodejs)
- [Native ES modules or TypeScript](#native-es-modules-or-typescript)

• API Reference

• License

Pre-requisites

• Node.jsnode-js-url >= 8.9.0
• NPMnpm-url >= 5.5.1 (NPMnpm-url comes with Node.jsnode-js-url so there is no need to install separately.)

Setup

Install

# Install via NPM
$ npm install --save fb.me

Usage

// src/on-handlers.ts

export async function onMessageHandler(sender, text) {
  // Handler message text here...
}

export async function onPostbackHandler(sender, postback) {
  // Handler postback payload here...
}

export async function onQuickReplyHandler(sender, quickReply) {
  // Handler quick reply here...
}

Node.js

// src/server.js

/** Import project dependencies */
const https = require('https');
const express = require('express');
const {
  messageflow,
  handleDomainWhitelisting,
  setMessengerProfile,
} = require('fb.me');

/** Import other modules */
const {
  onMessageHandler,
  onPostbackHandler,
  onQuickReplyHandler,
} = require('./on-handlers');

/** Setting up */
const PORT = process.env.PORT;
const config = {
  appId: '<FB_APP_ID>',
  pageAccessToken: '<FB_PAGE_ACCESS_TOKEN>',
  pageId: '<FB_PAGE_ID>',
  url: '<FB_GRAPH_URL>',
  verifyToken: 'FB_VERIFY_TOKEN',

  fetchTimeout: 599e3,
  notificationType: 'REGULAR',
  typingDelay: 5e2,
  onMessage: onMessageHandler,
  onPostback: onPostbackHandler,
  onQuickReply: onQuickReplyHandler,
};
const options = {
  agent: new https.Agent({ keepAlive: true }),
};
const app = express()
  .use(express.json())
  .use(express.urlencoded({ extended: false }))
  .use('/', messageflow(config, options));

/** NOTE: Custom error handling */
app.use((err, req, res, next) => {
  console.error('🚨 Handle error', err);

  return res.send(err instanceof Error ? err.message : err);
});

app.listen(PORT, async () => {
    /** NOTE: Set domain whitelisting on server boots up */
    await handleDomainWhitelisting({
      url: config.url,
      pageAccessToken: config.pageAccessToken,
      domains: [
        'https://should-whitelist-url.com',
      ],
    });

    /** NOTE: Setup messenger profile */
    await setMessengerProfile({
      url: config.url,
      pageAccessToken: config.pageAccessToken,
      body: {
        get_started: {
          payload: 'FACEBOOK_WELCOME',
        },
      },
    });

    console.info(`@ Express server running at port ${PORT}...`;
  });

Native ES modules or TypeScript

// src/server.ts

// @ts-check

/** Import project dependencies */
import https from 'https';
import express from 'express';
import messageflow from 'fb.me';
import handleMessengerProfile from 'fb.me/handle-messenger-profile';
import handleDomainWhitelisting from 'fb.me/handle-domain-whitelisting';

/** Import other modules */
import {
  onMessageHandler,
  onPostbackHandler,
  onQuickReplyHandler,
} from './on-handlers';

/** Setting up */
const PORT = process.env.PORT;
const config = {
  appId: '<FB_APP_ID>',
  pageAccessToken: '<FB_PAGE_ACCESS_TOKEN>',
  pageId: '<FB_PAGE_ID>',
  url: '<FB_GRAPH_URL>',
  verifyToken: 'FB_VERIFY_TOKEN',

  fetchTimeout: 599e3,
  notificationType: 'REGULAR',
  typingDelay: 5e2,
  onMessage: onMessageHandler,
  onPostback: onPostbackHandler,
  onQuickReply: onQuickReplyHandler,
};
const options = {
  agent: new https.Agent({ keepAlive: true }),
};
const app = express()
  .use(express.json())
  .use(express.urlencoded({ extended: false }))
  .use('/', messageflow(config, options));

/** NOTE: Custom error handling */
app.use((err, req, res, next) => {
  console.error('🚨 Handle error', err);

  return res.send(err instanceof Error ? err.message : err);
});

app.listen(PORT, async () => {
    /** NOTE: Set domain whitelisting on server boots up */
    await handleDomainWhitelisting({
      url: config.url,
      pageAccessToken: config.pageAccessToken,
      domains: [
        'https://should-whitelist-url.com',
      ],
    });

    /** NOTE: Setup messenger profile */
    await handleMessengerProfile.set({
      url: config.url,
      pageAccessToken: config.pageAccessToken,
      body: {
        get_started: {
          payload: 'FACEBOOK_WELCOME',
        },
      },
    });

    console.info(`@ Express server running at port ${PORT}...`;
  });

API Reference

MessageflowConfig

• appId <stringstring-mdn-url> Facebook Application ID.
• pageAccessToken <stringstring-mdn-url> Facebook page access token.
• pageId <stringstring-mdn-url> Facebook Page ID.
• url <stringstring-mdn-url> Facebook Graph URL, e.g. https://graph.facebook.com/v2.11
• verifyToken <stringstring-mdn-url> Facebook verify token.
• fetchTimeout <numbernumber-mdn-url> Optional timeout for HTTP requests, e.g. 599e3
• notificationType <stringstring-mdn-url> Optional notification type. Possible values: NO_PUSH, REGULAR, SILENT_PUSH.
• typingDelay <numbernumber-mdn-url> Optional delay in between messages.

FacebookMessageEvent

• message <Objectobject-mdn-url> Message object.

- `payload` <[string][string-mdn-url]> Custom data provided by the app.

- `type` <[string][string-mdn-url]> `audio`, `fallback`, `file`, `image`, `location` or `video`.
- `payload` <[Object][object-mdn-url]> `multimedia` or `location` payload.
  - `url` <[string][string-mdn-url]> URL of the file. _A `url` payload is only provided with a `multimedia` payload._
  - `coordinates` <[Object][object-mdn-url]> Coordinates of a location. _A `coordinates` payload is only provided with a `location` payload._
    - `lat` <[number][number-mdn-url]> Latitude.
    - `long` <[number][number-mdn-url]> Longitude.

HandleMessengerCodeResponse

• uri <stringstring-mdn-url> URL to the generated messenger code.

handleMessengerCode(url, pageAccessToken, ref, imageSize, options)

• url <stringstring-mdn-url> Facebook Graph URL.
• pageAccessToken <stringstring-mdn-url> Facebook page access token.
• ref <stringstring-mdn-url> Optional ref string to pass to the chatbot when it is opened via scanning the code on Messenger. 250 character limit and accepts only these characters: a-z A-Z 0-9 +/=-.:_.
• imageSize <stringstring-mdn-url> Optional image size, in pixels. Supported range: 100 - 2000px. Defaults to 1000px.
• options <Objectobject-mdn-url> Optional request options. See node-fetch optionsnode-fetch-options-url for more details.
• returns: <Promisepromise-mdn-url<Objectobject-mdn-url>> Promise which resolves with an object that contains the URL to the image of the generated messenger code.

deleteMessengerProfile(url, pageAccessToken, fields, options)

• url <stringstring-mdn-url> Facebook Graph URL.
• pageAccessToken <stringstring-mdn-url> Facebook page access token.
• fields <Arrayarray-mdn-url<stringstring-mdn-url>> A list of Messenger Profile propertiesmessenger-profile-api-url to delete.
• options <Objectobject-mdn-url> Optional request options. See node-fetch optionsnode-fetch-options-url for more details.
• returns: <Promisepromise-mdn-url<Objectobject-mdn-url>> Promise which resolves with status of the operation.

getMessengerProfile(url, pageAccessToken, fields, options)

• url <stringstring-mdn-url> Facebook Graph URL.
• pageAccessToken <stringstring-mdn-url> Facebook page access token.
• fields <stringstring-mdn-url|Arrayarray-mdn-url<stringstring-mdn-url>> A list/ comma-separated list of Messenger Profile propertiesmessenger-profile-api-url to retrieve, e.g. account_linking_url,persistent_menu,get_started,greeting,whitelisted_domains,payment_settings,target_audience,home_url
• options <Objectobject-mdn-url> Optional request options. See node-fetch optionsnode-fetch-options-url for more details.
• returns: <Promisepromise-mdn-url<Objectobject-mdn-url>> Promise which resolves with status of the operation.

setMessengerProfile(url, pageAccessToken, body, options)

• url <stringstring-mdn-url> Facebook Graph URL.
• pageAccessToken <stringstring-mdn-url> Facebook page access token.
• body <Objectobject-mdn-url> Set the value of one or more Messenger Profile propertiesmessenger-profile-api-url in the format of '<PROPERTY_NAME>': '<NEW_PROPERTY_VALUE>'. Only properties specified in the request body will be overwritten.
• options <Objectobject-mdn-url> Optional request options. See node-fetch optionsnode-fetch-options-url for more details.
• returns: <Promisepromise-mdn-url<Objectobject-mdn-url>> Promise which resolves with status of the operation.

handleReceiveMessage(appConfig, event, options)

• appConfig <MessageflowConfigmessageflowconfig-url> Application configuration.
• event <FacebookMessageEventfacebookmessageevent-url> Facebook message event. See messages Webhook Event Referencemessages-webhook-event-reference-url for more details.
• options <Objectobject-mdn-url> Optional request options. See node-fetch optionsnode-fetch-options-url for more details.
• returns: <Promisepromise-mdn-url<any>> The method will forward the correct message based on its message type to the corresponding event handler to do more stuff on the received message. A text message will be forwarded to the onMessage method that needs to be defined by the user in the appConfig whereas a quickReply message will handled by the onQuickReply method.

handleReceivePostback(appConfig, event, options)

• appConfig <MessageflowConfigmessageflowconfig-url> Application configuration.
• event <FacebookMessageEventfacebookmessageevent-url> Facebook message event. See messages Webhook Event Referencemessages-webhook-event-reference-url for more details.
• options <Objectobject-mdn-url> Optional request options. See node-fetch optionsnode-fetch-options-url for more details.
• returns: <Promisepromise-mdn-url<any>> The method will forward all postback payload to a user-defined onPostback method in appConfig.

License