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. This is the long way of sending a message. You probably want to use shortcut Response.reply() instead.

The SDK sets the messaging_type for all messages to RESPONSE because most users will only send messages in response to their users’ actions. While it’s possible to use the SDK to send other message types, setting another messaging_type is currently unsupported.

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