Bottender Facebook

Facebook connector for Bottender.

Installation

npm install bottender-facebook bottender messaging-api-messenger

Requirement

Facebook App Graph API verion

Using the API version before v2.10 may cause unexpected behavior.
We highly recommend the API version after v2.11.

Subscribe to essential fields

You need to make sure the webhook of your page is subscribing to the feed field on API version after v2.11.

User Permissions Required

manage_pages
publish_pages - for public replies
read_page_mailboxes - for private replies

Example

const { Bot } = require('bottender');
const { createServer } = require('bottender/express');
const { FacebookConnector } = require('bottender-facebook');
 
// We can get `story_fbid` in URL query string
const POST_ID =
  process.env.POST_ID || `${process.env.PAGE_ID}_${process.env.STORY_FBID}`;
 
const bot = new Bot({
  connector: new FacebookConnector({
    accessToken: process.env.ACCESS_TOKEN,
    appSecret: process.env.APP_SECRET,
  }),
});
 
bot.onEvent(async context => {
  if (
    context.event.isCommentAdd &&
    context.event.comment.post_id === POST_ID &&
    context.event.comment.parent_id === POST_ID
  ) {
    await context.sendPrivateReply('OK!');
    await context.sendComment('Public comment!');
  }
});
 
const server = createServer(bot);

Custom Graph API version

The default Graph API version is v3.2 (recommended).
You can use other version by following this example:

const { Bot } = require('bottender');
const { FacebookConnector, FacebookClient } = require('bottender-facebook');
 
const bot = new Bot({
  connector: new FacebookConnector({
    appSecret: APP_SECRET,
    client: FacebookClient.connect({
      accessToken: ACCESS_TOKEN,
      version: '3.2',
    }),
  }),
});

API Reference

Client

client.sendComment(objectId, comment)

await client.sendComment('<object_id>', 'ok!'); // send as text message
await client.sendComment('<object_id>', { message: 'ok!' });
await client.sendComment('<object_id>', { attachment_id: '<attachment_id>' });
await client.sendComment('<object_id>', {
  attachment_share_url: 'https://example.com/img.gif',
});
await client.sendComment('<object_id>', {
  attachment_url: 'https://example.com/img.jpg',
});

client.sendPrivateReply(objectId, text)

await client.sendPrivateReply('<object_id>', 'ok!');

client.sendLike()
client.getComment()
client.getLikes()

Context

context.sendComment(comment)

await context.sendComment('ok!'); // send as text message
await context.sendComment({ message: 'ok!' });
await context.sendComment({ attachment_id: '<attachment_id>' });
await context.sendComment({
  attachment_share_url: 'https://example.com/img.gif',
});
await context.sendComment({ attachment_url: 'https://example.com/img.jpg' });

context.sendPrivateReply(text)

await context.sendPrivateReply('ok!');

context.sendLike()
context.getComment()

const comment = await context.getComment({ fields: ['message_tags'] });
 
console.log(comment);
// {
//   id: '2013582382205928_2258908961006601',
//   // facebook returns undefined as message_tags instead of empty array
//   // when there is no tag
//   message_tags: [
//     {
//       id: '1895382890692545',
//       length: 8,
//       name: 'Bot Demo',
//       offset: 0,
//       type: 'page'
//     },
//   ],
// }

context.getLikes()
context.canReplyPrivately()

await context.canReplyPrivately(); // true

Event

event.isFeed
event.isStatus
event.isStatusAdd
event.isStatusEdited
event.status
event.isPost
event.isPostRemove
event.post
event.isComment
event.isCommentAdd
event.isCommentEdited
event.isCommentRemove
event.isFirstLayerComment
event.comment
event.isLike
event.isLikeAdd
event.isLikeRemove
event.like
event.isReaction
event.isReactionAdd
event.isReactionEdit
event.isReactionRemove
event.reaction

Contributing

Pull Requests and issue reports are welcome. You can follow steps below to submit your pull requests:

Fork, then clone the repo:

git clone git@github.com:your-username/bottender-facebook.git

Install the dependencies:

cd bottender-facebook
yarn

Make sure the tests pass (including eslint, flow checks and jest tests):

yarn test

Make your changes and tests, and make sure the tests pass.

bottender-facebook