@cs-chatbots/wingbot-facebook v3.1.2
Facebook Messenger plugin for wingbot
Connector plugin for wingbot chatbot framework
Advanced features
Transfering action as a metadata of handover event
You can include a full JSON Action string to run a certain interaction in your bot using metadata in a handover event.
{
"sender":{
"id":"<PSID>"
},
"recipient":{
"id":"<PAGE_ID>"
},
"timestamp":1458692752478,
"pass_thread_control":{
"new_owner_app_id":"123456789",
"metadata":"{\"action\":\"your-action\",\"data\":{}}"
}
}
API
Classes
Functions
Typedefs
Kind: global class
- Facebook
- new Facebook(processor, options, [senderLogger])
- .DEFAULT_EVENT_KEYS
- .verifyWebhook(queryString) ⇒ string
- .verifyRequest(body, headers) ⇒ Promise
- .processMessage(message, senderId, pageId, data) ⇒ Promise.<{status:number}>
- .processEvent(body, [data]) ⇒ Promise.<Array.<{message:object, pageId:string}>>
new Facebook(processor, options, senderLogger)
Param | Type | Description |
---|---|---|
processor | Processor | |
options | object | |
options.pageToken | string | facebook page token |
options.appId | string | facebook app id |
options.botToken | string | botToken for webhook verification |
options.appSecret | string | provide app secret to verify requests |
options.passThreadAction | string | trigger this action for pass thread event |
options.takeThreadAction | string | trigger this action for take thread event |
options.requestThreadAction | string | trigger this action when thread request |
options.allowEventKeys | Array.<string> | list of keys, allowed to process |
options.throwsExceptions | boolean | allows processEvents method to thow exception |
options.apiUrl | string | override Facebook API url |
options.attachmentStorage | AttachmentCache | cache for reusing attachments |
options.requestLib | function | request library replacement |
senderLogger | console | optional console like chat logger |
facebook.DEFAULT_EVENT_KEYS
Kind: instance property of Facebook
Properties
Name | Type | Description |
---|---|---|
Default | Array.<string> | keys allowed to process |
facebook.verifyWebhook(queryString) ⇒ string
Verifies Bots webhook against Facebook
Kind: instance method of Facebook
Throws:
- Error when the request is invalid
Param | Type |
---|---|
queryString | object |
facebook.verifyRequest(body, headers) ⇒ Promise
Verify Facebook webhook event
Kind: instance method of Facebook
Throws:
- Error when x-hub-signature does not match body signature
Param | Type |
---|---|
body | Buffer | string |
headers | object |
facebook.processMessage(message, senderId, pageId, data) ⇒ Promise.<{status:number}>
Kind: instance method of Facebook
Param | Type | Description |
---|---|---|
message | object | wingbot chat event |
senderId | string | chat event sender identifier |
pageId | string | channel/page identifier |
data | object | contextual data (will be available in res.data) |
data.appId | string | possibility to override appId |
facebook.processEvent(body, data) ⇒ Promise.<Array.<{message:object, pageId:string}>>
Process Facebook request
Kind: instance method of Facebook
Returns: Promise.<Array.<{message:object, pageId:string}>> - - unprocessed events
Param | Type | Description |
---|---|---|
body | object | event body |
data | object | event context data |
Settings
Kind: global class
- Settings
- new Settings()
- instance
- .greeting([text]) ⇒ Promise
- .getStartedButton([payload]) ⇒ Promise
- .whitelistDomain(domains) ⇒ Promise
- .noMenu() ⇒ Promise
- .menu([locale], [inputDisabled]) ⇒ MenuComposer
- static
new Settings()
Utility, which helps us to set up chatbot behavior
settings.greeting(text) ⇒ Promise
Sets or clears bot's greeting
Kind: instance method of Settings
Param | Type | Default | Description |
---|---|---|---|
text | string | false | leave empty to clear |
settings.getStartedButton(payload) ⇒ Promise
Sets up the Get Started Button
Kind: instance method of Settings
Param | Type | Default | Description |
---|---|---|---|
payload | string | object | false | leave blank to remove button, or provide the action |
Example
const settings = new Settings(config.facebook.pageToken);
settings.getStartedButton('/start'); // just an action
settings.whitelistDomain(domains) ⇒ Promise
Useful for using facebook extension in webviews
Kind: instance method of Settings
Param | Type |
---|---|
domains | string | Array.<string> |
settings.noMenu() ⇒ Promise
Drops the menu
Kind: instance method of Settings
settings.menu(locale, inputDisabled) ⇒ MenuComposer
Sets up the persistent menu
Kind: instance method of Settings
Param | Type | Default |
---|---|---|
locale | string | "default" |
inputDisabled | boolean | false |
Example
const { Settings } = require('wingbot');
const settings = new Settings('page-token-string');
settings
.menu('fr_FR')
.addNested('Nested Menu')
.addUrl('Aller à google', 'https://google.com')
.done()
.addPostBack('Faire quelque chose', '/the/action')
.menu() // the default menu
.addNested('Nested Menu')
.addUrl('Go to google', 'https://google.com')
.done()
.addPostBack('Do something', '/the/action')
.done();
Settings.Settings
Kind: static class of Settings
new Settings(token, log, req)
Creates an instance of Settings.
Param | Type | Description |
---|---|---|
token | string | |
log | Object | |
req | function | request library for resting purposes |
MenuComposer
Kind: global class
new MenuComposer(onDone, isTopLevel)
Param | Type | Default |
---|---|---|
onDone | function | |
isTopLevel | boolean | true |
menuComposer.addPostBack(title, action, data) ⇒ this
Add postback to menu
Kind: instance method of MenuComposer
Param | Type |
---|---|
title | string |
action | string |
data | object |
menuComposer.addUrl(title, url, hasExtension, webviewHeight) ⇒ this
Add webview to menu
Kind: instance method of MenuComposer
Param | Type | Default |
---|---|---|
title | string | |
url | string | |
hasExtension | boolean | false |
webviewHeight | string | null |
menuComposer.addNested(title) ⇒ MenuComposer
Add Nested menu component
Kind: instance method of MenuComposer
Param | Type |
---|---|
title | string |
menuComposer.done() ⇒ this | Promise
Finish the menu
Last call of "done" returns a promise
Kind: instance method of MenuComposer
menuComposer.menu(locale, inputDisabled) ⇒ MenuComposer
Finish the menu for the locale and starts a new menu
Kind: instance method of MenuComposer
Param | Type | Default |
---|---|---|
locale | string | "default" |
inputDisabled | boolean | false |
userLoader(pageToken, logger)
User loader middleware
Kind: global function
Param | Type |
---|---|
pageToken | string |
logger | console |
Example
const { userLoader } = require('wingbot-facebook');
bot.use(userLoader('<page token here>'));
bot.use((req, res) => {
const {
firstName,
lastName,
profilePic,
locale,
gender
} = req.state.user;
res.text(`Hello ${firstName}!`);
});
AttachmentCache : object
Kind: global typedef
Properties
Name | Type |
---|---|
findAttachmentByUrl | function |
saveAttachmentId | function |