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

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 |