messenger-wrapper
A simple library for handling Facebook Messenger Bots.
Installation
Execute this line in your app directory:
npm install --save messenger-wrapper
Import library into your app:
;
Initialize it:
let messenger = verifyToken: '<VERIFY_TOKEN>' pageAccessToken: '<PAGE_ACCESS_TOKEN>';
and you are ready to go.
Configuration (facebook's side)
First of all visit this official tutorial and make sure you complete these 3 steps:
Subscribe the App to a Page - remember that instead of making subscription call manually:
curl -X POST "https://graph.facebook.com/v2.6/me/subscribed_apps?access_token=<PAGE_ACCESS_TOKEN>"
You can always run you express app with all necessary routes defined and go under /subscribe
. See the first example for more details.
Steps:
-
Create page on Facebook or use existing one if you already have it
-
create app on Facebook or use existing one if you already have it
-
visit your developer account and get
PAGE_ACCESS_TOKEN
to initialize wrapper
Express.js (example usage)
This is sample usage within express.js application. For full example look here.
; //let's initialize our wrapper herelet messenger = verifyToken: '<VERIFY_TOKEN>' pageAccessToken: '<PAGE_ACCESS_TOKEN>'; //here we define 3 available listeners: 'message', 'delivery', 'postback' and 'optin':messenger; messenger; messenger; messenger; //this route is needed for facebook messenger verificationapp; //according to documentation https://developers.facebook.com/docs/messenger-platform/implementation//instead of sending this request manually -> curl -X POST "https://graph.facebook.com/v2.6/me/subscribed_apps?access_token=<PAGE_ACCESS_TOKEN>"//you can just run your express app and go under /subscribe in your web browserapp; //here we handle messenger data, you've got nothing to do here, just define that routeapp;
Documentation
Events
Basically we have 3 types of events according to Facebook documentation:
ATTENTION:
(event)
param here is optional, you can omit it, and it's only purpose is to show you incoming data. According to Facebook documentation
each incoming data can containt multiple entries
, that's why this library supports iterating over them in background and emits proper
actions, so you don't have to worry about losing any data. To get latest entry you should use messenger.lastEntry
object or use dedicated methods like send()
or getUserId()
(and more soon
) that operate on messenger.lastEntry
object. Go through
documentation to see examples.
messenger.on('message', (event))
Event triggered when the bot receives message from the user.
event
- object with payload received from messenger user
Example usage:
messenger;
messenger.on('delivery', (event))
Event triggered when the message has been successfully delivered to the user.
event
- object with payload received from messenger user
Example usage:
messenger;
messenger.on('postback', (event))
Event triggered when the postback action is triggered by the user.
event
- object with payload received from messenger user
Example usage:
messenger;
messenger.on('optin', (event))
Event triggered when the optin action is triggered by the user.
event
- object with payload received from messenger user
Example usage:
messenger;
Functions
messenger.send(payload)
payload
- object with data that will be send to the user, see docs for format specification
Example usage:
messenger;
messenger.getUser()
Returns object with user data:
first_name
last_name
profile_pic
Example usage:
messenger;
messenger.getUserId()
Returns ID of the user who sent the message.
Example usage:
messenger;
Elements
MessengerText(text)
text
- your text message to the user
This element can be sent separately.
Returns proper text hash:
text: 'text attribute'
Example usage:
; messenger;
MessengerImage(url)
url
- url to the image
This element can be sent separately.
Returns proper image hash:
attachment: type: 'image' payload: url: 'http://yoururl.com/image'
Example usage:
; messenger;
MessengerButton(attrs)
attrs
- object containing two attributes:
{ url: 'url', title: 'title' }
or { title: 'title', payload: 'payload' }
This element CANNOT be sent separately. Use it with Button, Generic or Receipt templates.
Returns proper button hash depending on attributes set:
First:
type: 'web_url' url: 'url' title: 'title'
Second:
type: 'postback' title: 'title' payload: 'payload'
Example usage (with MessengerButtonTemplate):
; messenger;
MessengerBubble(attrs)
attrs
- hash attributes defined in Facebook documentation
This element CANNOT be sent separately. Use it with Generic or Receipt templates.
Returns attrs
object:
title: 'Title' item_url: 'http://www.example.com' image_url: 'http://www.example.com' subtitle: 'Subtitle' buttons: type: 'web_url' title: 'Button' url: 'http://www.example.com'
Example usage:
; ... itle: 'Title' item_url: 'http://www.example.com' image_url: 'http://www.example.com' subtitle: 'Subtitle' buttons: title: 'Web Url Button' url: 'http://www.example.com' title: 'Postback Button' payload: 'POSTBACK_INFO' ;...
MessengerAddress(attrs)
attrs
- hash attributes defined in Facebook documentation
This element CANNOT be sent separately. Use it with Receipt template.
Returns attrs
object:
street_1: '1 Hacker Way' street_2: '' city: 'Menlo Park' postal_code: '94025' state: 'CA' country: 'US'
Example usage:
; ... street_1: '1 Hacker Way' street_2: '' city: 'Menlo Park' postal_code: '94025' state: 'CA' country: 'US';...
MessengerSummary(attrs)
attrs
- hash attributes defined in Facebook documentation
This element CANNOT be sent separately. Use it with Receipt template.
Returns attrs
object:
subtotal: 7500 shipping_cost: 495 total_tax: 619 total_cost: 5614
Example usage:
; ... subtotal: 7500 shipping_cost: 495 total_tax: 619 total_cost: 5614;...
MessengerAdjustment(text, amount)
text
- text attribute according to Facebook documentation
amount
- amount attribute according to Facebook documentation
This element CANNOT be sent separately. Use it with Receipt template.
Returns attrs
object:
name: 'Adjustment' amount: 20
Example usage:
; ... name: 'Adjustment' amount: 20;...
Templates
MessengerButtonTemplate(text, buttons)
text
- text attribute
buttons
- array with buttons
Returns proper template object:
attachment: type: 'template' payload: template_type: 'button' text: 'Hello user!' buttons: type: 'web_url' title: 'Button' url: 'http://www.example.com'
Example usage:
; messenger;
MessengerGenericTemplate(bubbles)
bubbles
- array with bubbles
Returns proper generic template object:
attachment: type: 'template' payload: template_type: 'generic' elements: title: 'Title' item_url: 'http://www.example.com' image_url: 'http://www.example.com' subtitle: 'Subtitle' buttons: type: 'web_url' title: 'Button' url: 'http://www.example.com'
Example usage:
; messenger;
MessengerReceiptTemplate(attrs)
attrs
- attributes hash according to Facebook documentation
Returns proper receipt template object:
attachment: type: 'template' payload: template_type: 'receipt' recipient_name: 'Name' order_number: '123' currency: 'USD' payment_method: 'Visa' order_url: 'http://www.example.com' timestamp: '123123123' elements: title: 'Title' item_url: 'http://www.example.com' image_url: 'http://www.example.com' subtitle: 'Subtitle' buttons: type: 'web_url' title: 'Button' url: 'http://www.example.com' address: street_1: '1 Hacker Way' street_2: '' city: 'Menlo Park' postal_code: '94025' state: 'CA' country: 'US' summary: subtotal: 7500 shipping_cost: 495 total_tax: 619 total_cost: 5614 adjustments: name: 'Adjustment' amount: 20
Example usage:
; messenger