Skip to content

Latest commit

 

History

History
456 lines (325 loc) · 19.1 KB

Readme.md

File metadata and controls

456 lines (325 loc) · 19.1 KB
Raw

Botmaster-messenger

Build Status Coverage Status npm-version license

This is the FB messenger integration for botmaster. It allows you to use your botmaster bot on FB Messenger

Botmaster is a lightweight chatbot framework. Its purpose is to integrate your existing chatbot into a variety of messaging channels - currently Facebook Messenger, Twitter DM and Telegram.

Documentation

Find the whole documentation for the Botmaster framework on: http://botmasterai.com/documentation/latest

Installing

yarn add botmaster-messenger

or

npm install --save botmaster-messenger

Getting your Credentials

If you don't already have these, follow the steps 1-4 on the Facebook Messenger guide: https://developers.facebook.com/docs/messenger-platform/guides/quick-start

In step 2, where you setup your webhook, no need to code anything. Just specify the webhook, enter any secure string you want as a verify token(verifyToken) and copy that value in the settings object. Also, click on whichever message [those are "update"s using botmaster semantics] type you want to receive from Messenger (message_deliveries, messages, message_postbacks etc...).

To find your Facebook App Secret (fbAppSecret), navigate to your apps dashboard and under App Secret click show, enter your password if prompted and then there it is.

Code

Example code using a single page for a bot. When using a single page, botmaster can be used as expected.

const Botmaster = require('botmaster');
const MessengerBot = require('botmaster-messenger');
const botmaster = new Botmaster();

const messengerSettings = {
  credentials: {
    verifyToken: 'YOUR verifyToken',
    pageToken: 'YOUR pageToken',
    fbAppSecret: 'YOUR fbAppSecret',
  },
  webhookEndpoint: 'webhook1234',
};

const messengerBot = new MessengerBot(messengerSettings);

botmaster.addBot(messengerBot);

botmaster.use({
  type: 'incoming',
  name: 'my-middleware',
  controller: (bot, update) => {
    return bot.reply(update, 'Hello world!');
  }
});

multi-page bot example

const Botmaster = require('botmaster');
const MessengerBot = require('botmaster-messenger');
const botmaster = new Botmaster();

const messengerSettings = {
  credentials: {
    verifyToken: 'YOUR_VERIFY_TOKEN',
    fbAppSecret: 'YOUR_FB_APP_SECRET',
    pages: {
      'YOUR_PAGE_ID_1': {
        pageToken: 'YOUR_PAGE_TOKEN_1',
      },
      'YOUR_PAGE_ID_2': {
        pageToken: 'YOUR_PAGE_TOKEN_2',
      },
    },
  },
  webhookEndpoint: 'webhook1234',
};

const messengerBot = new MessengerBot(messengerSettings);

botmaster.addBot(messengerBot);

botmaster.use({
  type: 'incoming',
  name: 'my-middleware',
  controller: (bot, update) => {
    // 1) if you simply want to respond as the page that received the update.
    bot.reply(update, 'Hello World');
    // 2) or if you want to specify another page to response as, you can always set
    // the messageToSend.sender.id param as some other pageId as such.
    const messageToSend = bot.createOutgoingMessageFor(update.sender.id); // or any other page-scoped userId you know is using your page
    messageToSend.addText('Hello World');
    messageToSend.sender = {
      id: 'SOME_PAGE_ID', // update.sender.id would be this page. But you can set it to something else.
    };
    return bot.sendMessage(messageToSend);
  }
});

Webhooks

If you are not too sure how webhooks work and/or how to get them to run locally, go to webhooks to read some more.

API

MessengerBot

Extends BaseBot

The class to use if you want to add support for FB Messenger in your Botmaster project.

Parameters

  • settings

constructor

Constructor to the MessengerBot class

Parameters

  • settings object MessengerBot take a settings object as first param.

Examples

// single page bot
const messengerBot = new MessengerBot({
  credentials: {
    verifyToken: 'YOUR verifyToken',
    pageToken: 'YOUR pageToken',
    fbAppSecret: 'YOUR fbAppSecret',
  },
  webhookEndpoint: 'someEndpoint'
})
// multi-page bot
const messengerBot = new MessengerBot({
  credentials: {
    verifyToken: 'YOUR_VERIFY_TOKEN',
    fbAppSecret: 'YOUR_FB_APP_SECRET',
    pages: {
      'YOUR_PAGE_ID_1': {
         pageToken: 'YOUR_PAGE_TOKEN_1',
       },
      'YOUR_PAGE_ID_2': {
         pageToken: 'YOUR_PAGE_TOKEN_2',
       },
      etc...
    },
  },
  webhookEndpoint: 'someEndpoint'
})

_setGetStartedButton

Adds get start button to your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/get-started-button

Parameters

  • getStartedButtonPayload string The payload of the postback you will get when a user clicks on the get started button.
  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_getGetStartedButton

gets get started button payload from your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/get-started-button

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_removeGetStartedButton

removes get started button from your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/get-started-button

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_setPersistentMenu

Adds account Linking to your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/persistent-menu

Parameters

  • persistentMenu string persistent menu to use for your messenger bot
  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_getPersistentMenu

get persistent menu from your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/persistent-menu

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_removePersistentMenu

removes persistent menu from your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/persistent-menu

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_setGreetingText

Adds greeting text to your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/greeting-text

Parameters

  • greetingObject string greeting objects. Can be localized.
  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_getGreetingText

get greeting text from your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/greeting-text

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_removeGreetingText

removes greeting text from bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/greeting-text

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_setWhitelistedDomains

Adds white listed domains to your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/domain-whitelisting

Parameters

  • domainNameLists string List of domains to whitelist.
  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_getWhitelistedDomains

get whitelisted domains from your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/greeting-text

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_removeWhitelistedDomains

removes whitelisted domains from bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/greeting-text

Parameters

  • domainNameLists
  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_setAccountLinkingUrl

Adds account Linking url to your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/account-linking-url

Parameters

  • accountLinkingURL string Authentication callback URL. Must use https protocol.
  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_getAccountLinkingUrl

get account linking url from your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/account-linking-url

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_removeAccountLinkingUrl

removes account Linking to your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/account-linking-url

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId

_setTargetAudience

Adds target audience url to your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/target-audience

Parameters

  • targetAudience string
  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_getTargetAudience

get target audience url from your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/target-audience

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_removeTargetAudience

removes target audience to your bot. Read more here: https://developers.facebook.com/docs/messenger-platform/messenger-profile/target-audience

Parameters

  • resolveWithFullResponse boolean? specify wether request should resolve with full response or not. By default, this is false
  • pageId string? specify the page you want to set the get started button for. This iw valid only if you are using botmaster-messenger with multiple pages

_getUserInfoFromPage

get the info for a certain user from a certain page

Parameters

  • userId string id of the user whose information is requested
  • pageId string specify the page you want to get the user info from. Different pages may have different rights.

Contributing

In order to contribute, you will need to make sure the tests run on your local machine. To do so, follow these steps:

  1. Create a ./tests/_config.js file that looks like this:
'use strict';

const config = {
  messengerCredentials: () => ({
    verifyToken: 'YOUR_VERIFY_TOKEN',
    pageToken: 'YOUR_PAGE_TOKEN',
    fbAppSecret: 'YOUR_FB_APP_SECRET',
  }),

  messengerMultiPageCredentials: () => ({
    verifyToken: 'YOUR_VERIFY_TOKEN',
    fbAppSecret: 'YOUR_FB_APP_SECRET',
    pages: {
      'YOUR_PAGE_ID_1': {
        pageToken: 'YOUR_PAGE_TOKEN_1',
      },
      'YOUR_PAGE_ID_2': {
        pageToken: 'YOUR_PAGE_TOKEN_2',
      },
    },
  }),

  messengerUserId: () => 'YOUR_USER_ID_FOR_THIS_PAGE', // who to send messages to in tests (most probably one of your accounts)
  messengerBotId: () => 'YOUR_BOT_ID', // the id of the bot (as sent in message updates). I.E. your page id
};

module.exports = config;

This file is gitignored so won't be committed.

  1. Just run the tests

yarn test

License

This library is licensed under the MIT license