@cs-chatbots/wingbot-facebook

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

Facebook

Settings

MenuComposer

Functions

userLoader(pageToken, [logger])

User loader middleware

Typedefs

AttachmentCache : object

Facebook

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
    • .Settings
      • new Settings(token, [log], [req])

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

• MenuComposer
  • new MenuComposer(onDone, [isTopLevel])
  • .addPostBack(title, action, [data]) ⇒ this
  • .addUrl(title, url, [hasExtension], [webviewHeight]) ⇒ this
  • .addNested(title) ⇒ MenuComposer
  • .done() ⇒ this | Promise
  • .menu([locale], [inputDisabled]) ⇒ MenuComposer

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