Launch Vehicle FBM

Quick Start

You can follow along with this example at https://github.com/stripethree/enterprise-fbm

Prerequisites

You should have a test page, test app, webhook, and these environment variables:

• FACEBOOK_APP_ID
• FACEBOOK_PAGE_ID
• MESSENGER_APP_SECRET
• MESSENGER_PAGE_ACCESS_TOKEN
• MESSENGER_VALIDATION_TOKEN
• SERVER_URL

You can find a walkthrough that gives you this information at: https://developers.facebook.com/docs/messenger-platform/getting-started/quick-start

These instructions are written for a Node 6+ and npm 5+ development environment.

create config/custom-environment-variables.json with these contents:

{
  "launch-vehicle-fbm": {
    "facebook": {
      "appId": "FACEBOOK_APP_ID",
      "pageId": "FACEBOOK_PAGE_ID"
    },
    "messenger": {
      "appSecret": "MESSENGER_APP_SECRET",
      "pageAccessToken": "MESSENGER_PAGE_ACCESS_TOKEN",
      "validationToken": "MESSENGER_VALIDATION_TOKEN"
    },
    "port": "NODE_PORT",
    "serverUrl": "SERVER_URL"
  }
}

and config/default.json with these contents:

{
  "launch-vehicle-fbm": {
    "port": 3000
  }
}

For your webhook, you’ll probably need someting like Localtunnel or Ngork.

With that, you can set up your webhook url and the environment variable: SERVER_URL

Hello world

Let’s make a basic echo bot.

In a clean subdirectory:

npm init --force
npm install launch-vehicle-fbm

Now create index.js:

const { Messenger, Text } = require('launch-vehicle-fbm')
const messenger = new Messenger()

messenger.start()

messenger.on('message.text', ({reply, text}) => {
  reply(new Text(`Echo: "${text}"`))
})

Run the bot:

DEBUG=messenger* node index.js

Now you can message your page like:

For more advanced usage, continue reading https://github.com/stripethree/enterprise-fbm and the wiki.

Sending responses to the user

You’re given a reply function in event emitters. When called, it sends the first argument, responseMessage, back to the user:

messenger.on('text', ({ reply, text }) => {
  reply(responseMessage)
})

The classic, deprecated syntax will also work if you only have one page:

messenger.on('text', ({ senderId, text }) => {
  messenger.send(senderId, responseMessage)
})

The reply version is preferred because it’s more concise and gracefully handles multiple Pages.

If you have multiple Pages or send messages out of band, use Messenger.pageSend():

messenger.on('text', ({ senderId, text, session }) => {
  const pageId = magic()
  messenger.pageSend(pageId, senderId, responseMessage)
})

Some factories for generating responseMessage are available at the top level and are also available in a responses object if you need a namespace:

const { Text, Image, Generic } = require('launch-vehicle-fbm');
const { responses } = require('launch-vehicle-fbm');
// responses.Text, responses.Image, responses.Generic, etc.

The most common response is text:

new Text('Hello World')

Images just need a url. These also show up in the “Shared Photos” rail.

new Image('https://i.imgur.com/ehSTCkO.gif')

The full list of responses you can make are:

class Text(text, args)

Create a text response message

Text supports gettext-like functionality if your project has a messages.js in its root. Using this sample messages.js:

module.exports = {
  greeting_msg: 'Hello World!',
  error_count: 'Errors found: %d'
};

new Text('greeting_msg') would be equivalent to new Text('Hello World!').

You can also use printf-like syntax, like:

• new Text('error_count', 12)
• new Text('I have %d %s', 20, 'cabbages')

Arguments:

• text (string) – Text to send
• args (mixed) – Any printf substitution arguments

Text.quickReplies(buttons)

Add quick replies to the Text message

Arguments:

• buttons (Array.<Button>) – Buttons to attach. See quick-replies

Returns:

Text – returns itself for chaining

class Image(url)

Create an Image response message

Arguments:

• url (string) – URL of the image

Image.quickReplies(buttons)

Add quick replies to the Image message

Arguments:

• buttons (Array.<Button>) – Buttons to attach. See quick-replies

Returns:

Image – returns itself for chaining

class Generic(elements)

A Generic template. These are the rich elements you’ll use to create interactive elements and carousels.

Arguments:

• elements (Array.<Object>) – Generic template elements

API reference

class Messenger()

Messenger

Messenger.pageSend(pageId, recipientId, responseMessage)

Send a response to a user at a page. You probably want to use Response.reply() instead

Arguments:

• pageId (string) – Page ID
• recipientId (string) – Recipient ID
• responseMessage (Object) – The response message to send back

Returns:

Promise – A promise for sending the response

Messenger.send(recipientId, responseMessage)

Send a response to the default page

Deprecated since version 1.4.0: Use Response.reply() instead

Arguments:

• recipientId (number) – Recipient ID
• responseMessage (Object) – The response message to send back

Returns:

Promise – A promise for sending the response

Messenger.start()

Start the web server and listen for messages

Returns:void –

class Response(messenger, options)

Class representing a Messenger response

Response.reply(responseMessage)

Reply with a response

Arguments:

• responseMessage (Object) – The response message to send back

Returns:

Promise – When the reply is done

• Index