Home

Awesome

messenger-bot

Build Status Coverage Status npm version js-standard-style

A Node client for the Facebook Messenger Platform.

Requires Node >=4.0.0.

Installation

npm install messenger-bot

Example

See more examples in the examples folder.

Run this example in the cloud: Nitrous Quickstart

const http = require('http')
const Bot = require('messenger-bot')

let bot = new Bot({
  token: 'PAGE_TOKEN',
  verify: 'VERIFY_TOKEN',
  app_secret: 'APP_SECRET'
})

bot.on('error', (err) => {
  console.log(err.message)
})

bot.on('message', (payload, reply) => {
  let text = payload.message.text

  bot.getProfile(payload.sender.id, (err, profile) => {
    if (err) throw err

    reply({ text }, (err) => {
      if (err) throw err

      console.log(`Echoed back to ${profile.first_name} ${profile.last_name}: ${text}`)
    })
  })
})

http.createServer(bot.middleware()).listen(3000)
console.log('Echo bot server running at port 3000.')

Usage

Functions

let bot = new Bot(opts)

Returns a new Bot instance.

opts - Object

bot.middleware()

The main middleware for your bot's webhook. Returns a function. Usage:

const http = require('http')
const Bot = require('messenger-bot')

let bot = new Bot({
  token: 'PAGE_TOKEN',
  verify: 'VERIFY_TOKEN'
})

http.createServer(bot.middleware()).listen(3000)

As well, it mounts /_status, which will return {"status": "ok"} if the middleware is running. If verify is specified in the bot options, it will mount a handler for GET requests that verifies the webhook.

bot.sendMessage(recipient, payload, [callback], [messagingType], [tag])

Sends a message with the payload to the target recipient, and calls the callback if any. Returns a promise. See Send API.

bot.getAttachmentUploadId(url, is_reusable, type, [callback])

Sends the media to the Attachment Upload API and calls the callback if the upload is successful, including the attachment_id. See Attachment Upload API.

bot.sendSenderAction(recipient, senderAction, [callback])

Sends the sender action senderAction to the target recipient, and calls the callback if any. Returns a promise.

bot.unlinkAccount(psid, [callback])

Unlinks the user with the corresponding psid, and calls the callback if any. Returns a promise. See [Account Unlink Endpoint].(https://developers.facebook.com/docs/messenger-platform/identity/account-linking?locale=en_US#unlink)

bot.setGetStartedButton(payload, [callback])

bot.setPersistentMenu(payload, [callback])

Sets settings for the Get Started Button / Persistent Menu. See the Messenger Profile Reference for what to put in the payload.

bot.removeGetStartedButton([callback])

bot.removePersistentMenu([callback])

Removes the Get Started Button / Persistent Menu.

bot.getProfile(target, [callback])

Returns a promise of the profile information of the target, also called in the callback if any. See User Profile API.

{
  "first_name": "Zach",
  "last_name": "Bruggeman",
  "profile_pic": "<url to profile picture>",
  "locale": "en",
  "timezone": "PST",
  "gender": "M"
}

bot._handleMessage(payload)

The underlying method used by bot.middleware() to parse the message payload, and fire the appropriate events. Use this if you've already implemented your own middleware or route handlers to receive the webhook request, and just want to fire the events on the bot instance. See the echo bot implemented in Express for an example.

bot._verify(req, res)

The underlying method used by bot.middleware() for the initial webhook verification. Use this if you've already implemented your own middleware or route handlers, and wish to handle the request without implementing bot.middleware(). See the echo bot implemented in Express for an example.

Events

bot.on('message', (payload, reply, actions))

Triggered when a message is sent to the bot.

bot.on('message', (payload, reply, actions) => {
  reply({ text: 'hey!'}, (err, info) => {})
})

bot.on('postback', (payload, reply, actions))

Triggered when a postback is triggered by the sender in Messenger.

bot.on('postback', (payload, reply, actions) => {
  reply({ text: 'hey!'}, (err, info) => {})
})

bot.on('delivery', (payload, reply, actions))

Triggered when a message has been successfully delivered.

bot.on('delivery', (payload, reply, actions) => {
  reply({ text: 'hey!'}, (err, info) => {})
})

bot.on('authentication', (payload, reply, actions))

Triggered when a user authenticates with the "Send to Messenger" plugin.

bot.on('authentication', (payload, reply, actions) => {
  reply({ text: 'thanks!'}, (err, info) => {})
})

bot.on('referral', (payload, reply, actions))

Triggered when an m.me link is used with a referral param and only in a case this user already has a thread with this bot (for new threads see 'postback' event)

bot.on('referral', (payload, reply, actions) => {
  reply({ text: 'welcome!'}, (err, info) => {})
})

bot.on('accountLinked', (payload, reply, actions))

Triggered when an account is linked with the Account Linking Process.

bot.on('accountLinked', (payload, reply, actions) => {
  reply({ text: 'Logged in!'}, (err, info) => {})
})

bot.on('accountUnlinked', (payload, reply, actions))

Triggered when an account is unlinked with the Account Unlink Endpoint or with an Log Out Button.

bot.on('accountLinked', (payload, reply, actions) => {
  reply({ text: 'Logged out!'}, (err, info) => {})
})