GitPedia

Fbmessenger node

FB messenger for node

From rickydunlop·Updated August 10, 2024·View on GitHub·

A library to integrate with the [Facebook Messenger Platform](https://developers.facebook.com/docs/messenger-platform). The project is written primarily in JavaScript, distributed under the MIT License license, first published in 2016. Key topics include: bot, chatbot, es6, facebook, fb.

fbmessenger

Greenkeeper badge
Build Status
Coverage Status
npm version
npm

A library to integrate with the Facebook Messenger Platform.

Notice:
Please see the CHANGELOG for any breaking changes.

Table of contents

<!-- MarkdownTOC depth="1" autolink="true" autoanchor="true" bracket="round" --> <!-- /MarkdownTOC -->

<a name="installation"></a>

Installation

Execute this line in your app directory:

yarn add fbmessenger

or for npm

npm install --save fbmessenger

Import library into your app:

javascript
import { Messenger } from 'fbmessenger';

Initialize it:

javascript
const messenger = new Messenger({
  pageAccessToken: '<PAGE_ACCESS_TOKEN>'
});

<a name="configuration-of-facebook-app"></a>

Configuration of facebook app

First of all visit the official tutorial and make sure you complete these 3 steps:

Steps:

<a name="expressjs-example-usage"></a>

Express.js (example usage)

This is basic usage within an express.js application. For more detailed example look here.

javascript
import bodyParser from 'body-parser';
import { Messenger } from 'fbmessenger';

// Configuring Body Parser middleware to parse the incoming JSON and Url-encoded data
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));

// Initialize Messenger
const messenger = new Messenger({
  pageAccessToken: '<PAGE_ACCESS_TOKEN>'
});

// here we define some listeners:
messenger.on('message', (event) => {
  // put your logic here
});

messenger.on('postback', (event) => {
  // put your logic here
});

// This example shows how to setup verification using express
app.get('/webhook', (req, res) => {
  if (req.query['hub.mode'] === 'subscribe' &&
    req.query['hub.verify_token'] === process.env.VERIFY_TOKEN) {
    res.send(req.query['hub.challenge']);
  } else {
    res.sendStatus(400);
  }
});


// This route handles the webhook callbacks from Facebook
app.post('/webhook', (req, res) => {
  res.sendStatus(200);
  messenger.handle(req.body);
});

<a name="verifying-requests"></a>

Verifying Requests

It's important but not fundamental to verify each request that your application receives to make sure that who is calling your /webhook endpoint is Facebook and not some other person. That could be done by through verifying the Signature Hash that Facebook sends on every request. You will need to have your APP_SECRET in hands for performing such verification.

javascript
// Function that verifies the signature hash
const verifyRequestSignature = (req, res, buf) => {
    const signature = req.headers['x-hub-signature'];

    if (!signature) {
        throw new Error('Couldn\'t validate the signature.');
    } else {
        const elements = signature.split('=');
        const signatureHash = elements[1];
        const expectedHash = crypto.createHmac('sha1', process.env.APP_SECRET).update(buf).digest('hex');

        if (signatureHash !== expectedHash) {
            throw new Error('Couldn\'t validate the request signature.');
        }
    }
};

// Pass a function that verifies the signature instead of just calling app.use(bodyParser.json())
app.use(bodyParser.json({ verify: verifyRequestSignature });

<a name="events"></a>

Events

Events are triggered when Facebook posts to your webhook url.
The following events can be listened for:

  • message
  • delivery
  • optin
  • read
  • account_linking
  • postback
  • referral
  • checkout_update
  • payment
  • pre_checkout

<a name="listening-for-events"></a>

Listening for events

javascript
messenger.on(<event>, (message) => {
	console.log(message);
});

example console output

javascript
{
  sender: {
    id: 1234,
  },
  recipient: {
    id: 1234,
  },
  timestamp: 1457764197627,
  message: {
  	text: 'Hello World!'
  }
}

<a name="sending-messages"></a>

Sending messages

Messages are sent using the send(message, recipient) method.
It returns a Promise (from node-fetch).

If replying to a user, the recipient can be obtained from message.sender.id in the event listener. Otherwise it should be a Facebook page scope ID from a database or other data store.

<a name="example"></a>

Send a simple text reply

javascript
messenger.on('message', (message) => {
  messenger.send({ text: 'Hello' }, message.sender.id);
});

<a name="catching-errors"></a>

Catching errors

You can add a catch to get errors from the request.

javascript
messenger.send({ text: "Hello" })
  .then(console.log(res))
  .catch(err => console.log(err));

or if using async/await you can wrap your code in a try/catch block

javascript
messenger.on('message', async (message) => {
  try {
	await messenger.send({ text: 'Hello' }, message.sender.id);
  } catch (err) {
  	console.error(err);
  }
});

<a name="getting-user-details"></a>

Get a user's details

Example usage:

javascript
messenger.getUser()
  .then((user) => {
    messenger.send({
  	  text: `Hey ${user.first_name} ${user.last_name}`
    }, message.sender.id);
});

Returns object with user data:

  • first_name
  • last_name
  • profile_pic
  • locale
  • timezone
  • gender
  • is_payment_enabled

<a name="elements"></a>

Elements

<a name="text"></a>

Text

https://developers.facebook.com/docs/messenger-platform/send-api-reference/text-message

Example usage:

javascript
import { Text } from 'fbmessenger';

messenger.send(new Text('Hello World!'), message.sender.id);

you can also just pass an object to the send method like this

javascript
{ text: 'Hello World!' }

<a name="button"></a>

Button

https://developers.facebook.com/docs/messenger-platform/send-api-reference/buttons

Example (with ButtonTemplate):

javascript
import {
  Button,
  ButtonTemplate
} from 'fbmessenger';

messenger.send(new ButtonTemplate({
  text: 'Hey user! Watch these buttons:',
  buttons: [
    new Button({
      type: 'web_url',
      title: 'Web Url Button',
      url: 'http://www.example.com',
    }),
    new Button({
      type: 'postback',
      title: 'Postback Button',
      payload: 'POSTBACK_INFO',
    }),
  ]
}), message.sender.id);

For more examples, check out the tests.

<a name="element"></a>

Element

https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template

Example usage:

javascript
import {
  Button,
  Element,
} from 'fbmessenger';

...
new Element({
  title: 'Title',
  item_url: 'http://www.example.com',
  image_url: 'http://www.example.com',
  subtitle: 'Subtitle',
  buttons: [
    new Button({
      type: 'web_url',
      title: 'Web Url Button',
      url: 'http://www.example.com',
     }),
    new Button({
      type: 'postback',
      title: 'Postback Button',
      payload: 'POSTBACK_INFO',
      })
  ]
});
...

<a name="address"></a>

Address

https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template

This element must be used with the Receipt template.

Example usage:

javascript
import { Address } from 'fbmessenger';

...
new Address({
  street_1: '1 Hacker Way',
  street_2: '',
  city: 'Menlo Park',
  postal_code: '94025',
  state: 'CA',
  country: 'US'
});
...

<a name="summary"></a>

Summary

https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template

This element must be used with the Receipt template.

Example usage:

javascript
import { Summary } from 'fbmessenger';

...
new Summary({
  subtotal: 75.00,
  shipping_cost: 4.95,
  total_tax: 6.19,
  total_cost: 56.14
});
...

<a name="adjustment"></a>

Adjustment

https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template

This element must be used with the Receipt template.

Example usage:

javascript
import { Adjustment } from 'fbmessenger';

...
new Adjustment({
  name: 'Adjustment',
  amount: 20
});
...

<a name="attachments"></a>

Attachments

<a name="image"></a>

Image

https://developers.facebook.com/docs/messenger-platform/send-api-reference/image-attachment

Example usage:

javascript
import { Image } from 'fbmessenger';

messenger.send(new Image({
  url: 'http://lorempixel.com/400/400/sports/1/',
}), message.sender.id);

<a name="audio"></a>

Audio

https://developers.facebook.com/docs/messenger-platform/send-api-reference/audio-attachment

Example usage:

javascript
import { Audio } from 'fbmessenger';

messenger.send(new Audio({
  url: 'http://example.com/audio.mp3',
}), message.sender.id);

<a name="video"></a>

Video

https://developers.facebook.com/docs/messenger-platform/send-api-reference/video-attachment

Example usage:

javascript
import { Video } from 'fbmessenger';

messenger.send(new Video({
  url: 'http://example.com/video.mp4',
}), message.sender.id);

<a name="file"></a>

File

https://developers.facebook.com/docs/messenger-platform/send-api-reference/file-attachment

Example usage:

javascript
import { File } from 'fbmessenger';

messenger.send(new File({
  url: 'http://example.com/file.txt',
}), message.sender.id);

<a name="reusable-attachments"></a>

Reusable attachments

Attachments can be reused by passing true as the second parameter. This sets the is_reusable flag.

javascript
const image = new Image({
  url: 'http://lorempixel.com/400/400/sports/1/',
  is_reusable: true
});
messenger.send(image, message.sender.id);

You can then use the attachment_id from the response to send the same attachment again

javascript
messenger.send(new Image({ attachment_id: 12345 }, message.sender.id);

Attachment Upload API

javascript
const image = new Image({
  url: 'http://lorempixel.com/400/400/sports/1/',
  is_reusable: true
});
messenger.messageAttachment(image);

This will return a reusable attachment ID.

<a name="templates"></a>

Templates

<a name="buttontemplate"></a>

ButtonTemplate

https://developers.facebook.com/docs/messenger-platform/send-api-reference/button-template

Example usage:

javascript
import {
  Button,
  ButtonTemplate
} from 'fbmessenger';

messenger.send(new ButtonTemplate({
  text: 'Hey user! Watch these buttons:',
  buttons: [
    new Button({
      type: 'web_url',
      title: 'Web Url Button',
      url: 'http://www.example.com',
    }),
    new Button({
      type: 'postback',
      title: 'Postback Button',
      payload: 'POSTBACK_INFO',
    })
  ]
}), message.sender.id);

GenericTemplate

https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template

Example usage:

javascript
import {
  Button,
  Element
  GenericTemplate
} from 'fbmessenger';

messenger.send(new GenericTemplate(
[
  new Element({
    title: 'Title',
    item_url: 'http://www.example.com',
    image_url: 'http://www.example.com',
    subtitle: 'Subtitle',
    buttons: [
      new Button({
        type: 'web_url',
        title: 'Button',
        url: 'http://www.example.com',
      }),
    ]
  }),
  ...
]
), message.sender.id);

ReceiptTemplate

https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template

Example usage:

javascript
import {
  Button,
  Element,
  Address,
  Summary,
  Adjustment,
  ReceiptTemplate
} from 'fbmessenger';

messenger.send(new ReceiptTemplate({
  recipient_name: 'Name',
  order_number: '123',
  currency: 'USD',
  payment_method: 'Visa',
  order_url: 'http://www.example.com',
  timestamp: '123123123',
  elements: [
    new Element({
      title: 'Title',
      image_url: 'http://www.example.com',
      subtitle: 'Subtitle',
      currency: 'USD',
      quantity: 1,
      price: 15
    })
  ],
  address: new Address({
    street_1: '1 Hacker Way',
    street_2: '',
    city: 'Menlo Park',
    postal_code: '94025',
    state: 'CA',
    country: 'US'
  }),
  summary: new Summary({
    subtotal: 75.00,
    shipping_cost: 4.95,
    total_tax: 6.19,
    total_cost: 56.14
  }),
  adjustments: [
    new Adjustment('Adjustment', 20)
  ]
}), message.sender.id);

<a name="thread-settings"></a>

Thread settings

<a name="greeting-text"></a>

Greeting Text

https://developers.facebook.com/docs/messenger-platform/thread-settings/greeting-text

javascript
import { GreetingText } from fbmessenger

const greeting = new GreetingText('Hello');
messenger.setThreadSetting(greeting);

There is also a method to delete the greeting text called deleteGreetingText

<a name="get-started-button"></a>

Get Started Button

https://developers.facebook.com/docs/messenger-platform/thread-settings/get-started-button

javascript
import { GetStartedButton } from 'fbmessenger';

const getStarted = new GetStartedButton('start');
messenger.setThreadSetting(getStarted);

When someone first interacts with your bot they will see a Get Started button. When this is clicked it will send a postback to your server with the value of start.

There is also a method to delete the Get Started Button called deleteGetStarted

<a name="persistent-menu"></a>

Persistent Menu

https://developers.facebook.com/docs/messenger-platform/thread-settings/persistent-menu

javascript
import {
  PersistentMenu,
  PersistentMenuItem
} from 'fbmessenger';

const item_1 = new PersistentMenuItem({
	item_type: 'web_url',
	title: 'Menu button 1',
	url: 'http://facebook.com'
});

const item_2 = new PersistentMenuItem({
	item_type: 'payload',
	title: 'Menu button 2',
	payload: 'menu_button_2'
});

const item_3 = new PersistentMenuItem({
	item_type: 'web_url',
	title: 'Menu button 3',
	url: 'http://facebook.com',
	webview_height_ratio: 'tall',
	messenger_extensions: true
});

const menu = new PersistentMenu([item_1, item_2, item_3]);
messenger.setThreadSetting(menu);

You can delete the Persistent Menu using the deletePersistentMenu method

<a name="sender-actions"></a>

Sender Actions

Available actions are

  • typing_on
  • typing_off
  • mark_seen
javascript
messenger.senderAction('typing_on', message.sender.id);

<a name="quick-replies"></a>

Quick Replies

Quick Replies work with all message types including text message, image and template attachments.

javascript
const reply1 = new QuickReply({
  title: 'Example',
  payload: 'payload',
});
const reply2 = new QuickReply({
  title: 'Location',
  content_type: 'location',
});
const quick_replies = new QuickReplies([reply1, reply2]);

const text = new Text('A simple text message')

const payload = Object.assign(text, quick_replies)

messenger.send(payload, message.sender.id)

<a name="whitelisted-domains"></a>

Whitelisted domains

<a name="adding"></a>

Adding

javascript
// Single
messenger.addWhitelistedDomain('http://example.com');

// Multiple
messenger.addWhitelistedDomains(['http://example.com', 'http://example2.com']);

<a name="removing"></a>

Removing

javascript
// Single
messenger.removeWhitelistedDomain('http://example.com');

// Multiple
messenger.removeWhitelistedDomains(['http://example.com', 'http://example2.com']);

Messenger Code API

javascript
messenger.messengerCode({ size: 1000 });
messenger.messengerCode({ ref: 'MY_REF' });

<a name="subscribing-an-app-to-a-page"></a>

Subscribing an app to a page

The easiest way to do this is now through the Facebook developer site. If you need to do this progamatically you can use subscribeAppToPage

<a name="account-linking"></a>

Account linking

You can link and unlink accounts with linkAccount and unlinkAccount

javascript
messenger.linkAccount('ACCOUNT_LINKING_TOKEN');
javascript
messenger.unlinkAccount('PSID');

<a name="sending-raw-payloads"></a>

Sending raw payloads

You can also send raw payloads with send. This lets you use any new features from Facebook while waiting for support to be added to this library.

javascript
messenger.on('message', () => {
  messenger.send({
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"button",
        "text":"What do you want to do next?",
        "buttons":[
          {
            "type":"web_url",
            "url":"https://petersapparel.parseapp.com",
            "title":"Show Website"
          }
        ]
      }
    }
  }, message.sender.id);
});

Contributors

Showing top 8 contributors by commit count.

rickydunlop

rickydunlop

51 commits

greenkeeper[bot]

greenkeeper[bot]

14 commits

greenkeeperio-bot

greenkeeperio-bot

13 commits

Tavernari

Tavernari

3 commits

saade

saade

2 commits

grieve

grieve

2 commits

achoisy

achoisy

2 commits

danfsd

danfsd

1 commits

View all contributors on GitHub →

This article is auto-generated from rickydunlop/fbmessenger-node via the GitHub API.Last fetched: 6/28/2026