A Node client for the Facebook Messenger Platform.
Requires Node >=4.0.0.
npm install messenger-bot
See more examples in the examples folder.
Run this example in the cloud:
- Setup
PAGE_TOKEN
,VERIFY_TOKEN
,APP_SECRET
and start the example byRun > Start Messenger Echo Bot
. - Your Webhook URL is available at
Preview > 3000
in the IDE.
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.')
Returns a new Bot instance.
opts
- Object
token
- String: Your Page Access Token, found in your App settings. Required.verify
- String: A verification token for the first-time setup of your webhook. Optional, but will be required by Facebook when you first set up your webhook.app_secret
- String: Your App Secret token used for message integrity check. If specified, every POST request will be tested for spoofing. Optional.
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.
Sends a message with the payload
to the target recipient
, and calls the callback if any. Returns a promise. See Send API.
recipient
- Number: The Facebook ID of the intended recipient.payload
- Object: The message payload. Should follow the Send API format.callback
- (Optional) Function: Called with(err, info)
once the request has completed.err
contains an error, if any, andinfo
contains the response from Facebook, usually with the new message's ID.
Sends the sender action senderAction
to the target recipient
, and calls the callback if any. Returns a promise.
recipient
- Number: The Facebook ID of the intended recipient.senderAction
- String: The sender action to execute. Can be one of:typing_on
, 'typing_off', 'mark_seen'. See the Send API reference for more information.callback
- (Optional) Function: Called with(err, info)
once the request has completed.err
contains an error, if any, andinfo
contains the response from Facebook, usually with the new message's ID.
Sets settings for the Get Started Button / Persistent Menu. See the Thread Settings Reference call_to_actions
sections for what to put in the payload
.
Removes the Get Started Button / Persistent Menu.
Returns a promise of the profile information of the target
, also called in the callback
if any. See User Profile API.
target
- Number: The Facebook ID of the intended target.callback
- (Optional) Function: Called with(err, profile)
once the request has completed.err
contains an error, if any, andinfo
contains the response from Facebook, in this format:
{
"first_name": "Zach",
"last_name": "Bruggeman",
"profile_pic": "<url to profile picture>",
"locale": "en",
"timezone": "PST",
"gender": "M"
}
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.
payload
- Object: The payload sent by Facebook to the webhook.
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.
req
- Request: Thehttp
request object.res
- Response: Thehttp
response object.
Triggered when a message is sent to the bot.
payload
- Object: An object containing the message event's payload from Facebook. See Facebook's documentation for the format.reply
- Function: A convenience function that callsbot.sendMessage
, with the recipient automatically set to the message sender's Facebook ID. Example usage:
bot.on('message', (payload, reply, actions) => {
reply({ text: 'hey!'}, (err, info) => {})
})
actions
- Object: An object with two functions:setTyping(status: Boolean)
, andmarkRead()
.
Triggered when a postback is triggered by the sender in Messenger.
payload
- Object: An object containing the postback event's payload from Facebook. See Facebook's documentation for the format.reply
- Function: A convenience function that callsbot.sendMessage
, with the recipient automatically set to the message sender's Facebook ID. Example usage:actions
- Object: An object with two functions:setTyping(status: Boolean)
, andmarkRead()
.
bot.on('postback', (payload, reply, actions) => {
reply({ text: 'hey!'}, (err, info) => {})
})
Triggered when a message has been successfully delivered.
payload
- Object: An object containing the delivery event's payload from Facebook. See Facebook's documentation for the format.reply
- Function: A convenience function that callsbot.sendMessage
, with the recipient automatically set to the message sender's Facebook ID. Example usage:actions
- Object: An object with two functions:setTyping(status: Boolean)
, andmarkRead()
.
bot.on('delivery', (payload, reply, actions) => {
reply({ text: 'hey!'}, (err, info) => {})
})
Triggered when a user authenticates with the "Send to Messenger" plugin.
payload
- Object: An object containing the authentication event's payload from Facebook. See Facebook's documentation for the format.reply
- Function: A convenience function that callsbot.sendMessage
, with the recipient automatically set to the message sender's Facebook ID. Example usage:actions
- Object: An object with two functions:setTyping(status: Boolean)
, andmarkRead()
.
bot.on('authentication', (payload, reply, actions) => {
reply({ text: 'thanks!'}, (err, info) => {})
})