Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/botmasterai/botmaster-messenger

The Facebook Messenger Botmaster integration
https://github.com/botmasterai/botmaster-messenger

Last synced: about 2 months ago
JSON representation

The Facebook Messenger Botmaster integration

Host: GitHub
URL: https://github.com/botmasterai/botmaster-messenger
Owner: botmasterai
License: mit
Created: 2017-02-27T23:13:16.000Z (almost 8 years ago)
Default Branch: master
Last Pushed: 2018-08-24T06:34:37.000Z (over 6 years ago)
Last Synced: 2024-04-26T23:40:48.020Z (8 months ago)
Language: JavaScript
Size: 164 KB
Stars: 15
Watchers: 5
Forks: 9
Open Issues: 3
Metadata Files:
- Readme: Readme.md
- License: LICENSE

Awesome Lists containing this project

README

# Botmaster-messenger

[![Build Status](https://travis-ci.org/botmasterai/botmaster-messenger.svg?branch=master)](https://travis-ci.org/botmasterai/botmaster-messenger)
[![Coverage Status](https://coveralls.io/repos/github/botmasterai/botmaster-messenger/badge.svg?branch=master)](https://coveralls.io/github/botmasterai/botmaster-messenger?branch=master)
[![npm-version](https://img.shields.io/npm/v/botmaster-messenger.svg)](https://www.npmjs.com/package/botmaster-messenger)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)](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:

## Installing

```bash
yarn add botmaster-messenger
```

```bash
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:

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.

```js
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

```js
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](/getting-started/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** MessengerBot take a settings
object as first param.

**Examples**

```javascript
// single page bot
const messengerBot = new MessengerBot({
credentials: {
verifyToken: 'YOUR verifyToken',
pageToken: 'YOUR pageToken',
fbAppSecret: 'YOUR fbAppSecret',
},
webhookEndpoint: 'someEndpoint'
})
```

```javascript
// 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:

**Parameters**

- `getStartedButtonPayload` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The payload of the postback
you will get when a user clicks on the get started button.
- `resolveWithFullResponse` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** specify wether request should
resolve with full response or not. By default, this is false
- `pageId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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:

**Parameters**

- `resolveWithFullResponse` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** specify wether request should
resolve with full response or not. By default, this is false
- `pageId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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:

**Parameters**

#### \_setPersistentMenu

Adds account Linking to your bot. Read more here:

**Parameters**

- `persistentMenu` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** persistent menu to use for your messenger
bot
- `resolveWithFullResponse` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** specify wether request should
resolve with full response or not. By default, this is false
- `pageId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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:

**Parameters**

#### \_removePersistentMenu

removes persistent menu from your bot. Read more here:

**Parameters**

#### \_setGreetingText

Adds greeting text to your bot. Read more here:

**Parameters**

- `greetingObject` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** greeting objects. Can be localized.
- `resolveWithFullResponse` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** specify wether request should
resolve with full response or not. By default, this is false
- `pageId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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:

**Parameters**

#### \_removeGreetingText

removes greeting text from bot. Read more here:

**Parameters**

#### \_setWhitelistedDomains

Adds white listed domains to your bot. Read more here:

**Parameters**

- `domainNameLists` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** List of domains to whitelist.
- `resolveWithFullResponse` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** specify wether request should
resolve with full response or not. By default, this is false
- `pageId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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:

**Parameters**

#### \_removeWhitelistedDomains

removes whitelisted domains from bot. Read more here:

**Parameters**

- `domainNameLists`
- `resolveWithFullResponse` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** specify wether request should
resolve with full response or not. By default, this is false
- `pageId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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:

**Parameters**

- `accountLinkingURL` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Authentication callback URL.
Must use https protocol.
- `resolveWithFullResponse` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** specify wether request should
resolve with full response or not. By default, this is false
- `pageId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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:

**Parameters**

#### \_removeAccountLinkingUrl

removes account Linking to your bot. Read more here:

**Parameters**

#### \_setTargetAudience

Adds target audience url to your bot. Read more here:

**Parameters**

- `targetAudience` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
- `resolveWithFullResponse` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** specify wether request should
resolve with full response or not. By default, this is false
- `pageId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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:

**Parameters**

#### \_removeTargetAudience

removes target audience to your bot. Read more here:

**Parameters**

#### \_getUserInfoFromPage

get the info for a certain user from a certain page

**Parameters**

- `userId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** id of the user whose information is requested
- `pageId` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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:

```js
'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.

2. Just run the tests

`yarn test`

## License

This library is licensed under the MIT [license](LICENSE)