Naphthalene Possum Management

    botmaster-messenger

    1.2.0 • Public • Published

    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

    Install

    npm i botmaster-messenger

    DownloadsWeekly Downloads

    18

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    304 kB

    Total Files

    25

    Last publish

    Collaborators

    • jdwuarin
    • jwickens