Bootbot

<p align="center"> <img src="./assets/logo.png" /> </p>

BootBot is a simple but powerful JavaScript Framework to build Facebook Messenger's Chat bots.

| [Features][] | [Usage][] | [Video Example][] | [Getting Started][] | [Documentation][] | [Examples][] | [Credits][] | [License][] | |---|---|---|---|---|---|---|---|

:speech_balloon: Questions / Comments? Join our Slack channel!

Features

• Helper methods to send any type of message supported by Facebook.
• Subscribe to a particular type of message, or to certain keywords sent by the user.
• Start conversations, ask questions and save important information in the context of the conversation.
• Organize your code in modules.
• Send automatic or manual typing indicators.
• Set your bot's properties, such as a persistent menu, a greeting text or a get started CTA.
• Subscribe to received and read events.

Usage

$ npm install bootbot --save

'use strict';
const BootBot = require('bootbot');

const bot = new BootBot({
  accessToken: 'FB_ACCESS_TOKEN',
  verifyToken: 'FB_VERIFY_TOKEN',
  appSecret: 'FB_APP_SECRET'
});

bot.on('message', (payload, chat) => {
  const text = payload.message.text;
  chat.say(`Echo: ${text}`);
});

bot.start();

Video Example

Creating a Giphy Chat Bot in 3 minutes:

Getting Started

• Install BootBot via NPM, create a new index.js, require BootBot and create a new bot instance using your Facebook Page's / App's accessToken, verifyToken and appSecret:

Note: If you don't know how to get these tokens, take a look at Facebook's Quick Start Guide or check out this issue.

// index.js
'use strict';
const BootBot = require('bootbot');

const bot = new BootBot({
  accessToken: 'FB_ACCESS_TOKEN',
  verifyToken: 'FB_VERIFY_TOKEN',
  appSecret: 'FB_APP_SECRET'
});

• Subscribe to messages sent by the user with the bot.on() and bot.hear() methods:

bot.on('message', (payload, chat) => {
	const text = payload.message.text;
	console.log(`The user said: ${text}`);
});

bot.hear(['hello', 'hi', /hey( there)?/i], (payload, chat) => {
	console.log('The user said "hello", "hi", "hey", or "hey there"');
});

• Reply to user messages using the chat object:

bot.hear(['hello', 'hi', /hey( there)?/i], (payload, chat) => {
	// Send a text message followed by another text message that contains a typing indicator
	chat.say('Hello, human friend!').then(() => {
		chat.say('How are you today?', { typing: true });
	});
});

bot.hear(['food', 'hungry'], (payload, chat) => {
	// Send a text message with quick replies
	chat.say({
		text: 'What do you want to eat today?',
		quickReplies: ['Mexican', 'Italian', 'American', 'Argentine']
	});
});

bot.hear(['help'], (payload, chat) => {
	// Send a text message with buttons
	chat.say({
		text: 'What do you need help with?',
		buttons: [
			{ type: 'postback', title: 'Settings', payload: 'HELP_SETTINGS' },
			{ type: 'postback', title: 'FAQ', payload: 'HELP_FAQ' },
			{ type: 'postback', title: 'Talk to a human', payload: 'HELP_HUMAN' }
		]
	});
});

bot.hear('image', (payload, chat) => {
	// Send an attachment
	chat.say({
		attachment: 'image',
		url: 'http://example.com/image.png'
	});
});

• Start a conversation and keep the user's answers in context:

bot.hear('ask me something', (payload, chat) => {

	const askName = (convo) => {
		convo.ask(`What's your name?`, (payload, convo) => {
			const text = payload.message.text;
			convo.set('name', text);
			convo.say(`Oh, your name is ${text}`).then(() => askFavoriteFood(convo));
		});
	};

	const askFavoriteFood = (convo) => {
		convo.ask(`What's your favorite food?`, (payload, convo) => {
			const text = payload.message.text;
			convo.set('food', text);
			convo.say(`Got it, your favorite food is ${text}`).then(() => sendSummary(convo));
		});
	};

	const sendSummary = (convo) => {
		convo.say(`Ok, here's what you told me about you:
	      - Name: ${convo.get('name')}
	      - Favorite Food: ${convo.get('food')}`);
      convo.end();
	};

	chat.conversation((convo) => {
		askName(convo);
	});
});

• Set up webhooks and start the express server:

bot.start();

• Start up your bot by running node:

$ node index.js
> BootBot running on port 3000
> Facebook Webhook running on localhost:3000/webhook

• If you want to test your bot locally, install a localhost tunnel like ngrok and run it on your bot's port:

$ ngrok http 3000

Then use the provided HTTPS URL to config your webhook on Facebook's Dashboard. For example if the URL provided by ngrok is https://99b8d4c2.ngrok.io, use https://99b8d4c2.ngrok.io/webhook.

Documentation

BootBot Class

new BootBot(options)

| options key | Type | Default | Required | |:--------------|:-----|:--------|:---------| | accessToken | string | | Y | | verifyToken | string | | Y | | appSecret | string | | Y | | webhook | string | "/webhook" | N | | broadcastEchoes | boolean | false | N | | graphApiVersion | string | v2.12 | N |

Creates a new BootBot instance. Instantiates the new express app and all required webhooks. options param must contain all tokens and app secret of your Facebook app. Optionally, set broadcastEchoes to true if you want the messages your bot send to be echoed back to it (you probably don't need this feature unless you have multiple bots running on the same Facebook page).

If you want to specify a custom endpoint name for your webhook, you can do it with the webhook option.

.start([ port ])

| Param | Type | Default | Required | |:------|:-----|:--------|:---------| | port | number | 3000 | N |

Starts the express server on the specified port. Defaults port to 3000.

.close()

Closes the express server (calls .close() on the server instance).

---

Receive API

Use these methods to subscribe your bot to messages, attachments or anything the user might send.

.on(event, callback)

| Param | Type | Default | Required | |:------|:-----|:--------|:---------| | event | string | | Y | | callback | function | | Y |

Subscribe to an event emitted by the bot, and execute a callback when those events are emitted. Available events are:

| Event | Description | |:------|:-----| | message | The bot received a text message from the user | | quick_reply | The bot received a quick reply from the user (quick replies emit both message and quick_reply events) | | attachment | The bot received an attachment from the user | | postback | The bot received a postback call from the user (usually means the user clicked a button) | | delivery | The bot received a confirmation that your message was delivered to the user | | read | The bot received a confirmation that your message was read by the user | | authentication | A user has started a conversation with the bot using a "Send to Messenger" button | | referral | A user that already has a thread with the bot starts a conversation. more |

You can also subscribe to specific postbacks and quick replies by using a namespace. For example postback:ADD_TO_CART subscribes only to the postback event containing the ADD_TO_CART payload.

If you want to subscribe to specific keywords on a message event, see the .hear() method below.

When these events ocurr, the specified callback will be invoked with 3 params: (payload, chat, data)

| Param | Description | |:------|:-----| | payload | The data sent by the user (contains the text of the message, the attachment, etc.) | | chat | A Chat instance that you can use to reply to the user. Contains all the methods defined in the Send API | | data | Contains extra data provided by the framework, like a captured flag that signals if this message was already captured by a different callback |

.on() examples:

bot.on('message', (payload, chat) => {
	console.log('A text message was received!');
});

bot.on('attachment', (payload, chat) => {
	console.log('An attachment was received!');
});

bot.on('postback:HELP_ME', (payload, chat) => {
	console.log('The Help Me button was clicked!');
});

bot.on('message', (payload, chat) => {
	// Reply to the user
	chat.say('Hey, user. I got your message!');
});

.hear(keywords, callback)

| Param | Type | Default | Required | |:------|:-----|:--------|:---------| | keywords | string, regex or mixed array | | Y | | callback | function | | Y |

A convinient method to subscribe to message events containing specific keywords. The keyword param can be a string, a regex or an array of both strings and regexs that will be tested against the received message. If the bot receives a message that matches any of the keywords, it will execute the specified callback. String keywords are case-insensitive, but regular expressions are not case-insensitive by default, if you want them to be, specify the i flag.

The callback's signature is identical to that of the .on() method above.

.hear() examples:

bot.hear('hello', (payload, chat) => {
	chat.say('Hello, human!');
});

bot.hear(['hello', 'hi', 'hey'], (payload, chat) => {
	chat.say('Hello, human!');
});

bot.hear([/(good)?bye/i, /see (ya|you)/i, 'adios'], (payload, chat) => {
	// Matches: goodbye, bye, see ya, see you, adios
	chat.say('Bye, human!');
});

Note that if a bot is subscribed to both the message event using the .on() method and