diff --git a/lib/Facebook.js b/lib/Facebook.js index 947c77f07..636f6b434 100644 --- a/lib/Facebook.js +++ b/lib/Facebook.js @@ -185,7 +185,80 @@ function Facebookbot(configuration) { cb(); }; + + // Setup a handler to set the payload for Get Started button + bot.setGetStartedPayload = function(get_started_payload, cb) { + get_started_message = { + "setting_type":"call_to_actions", + "thread_state":"new_thread", + "call_to_actions":[ + { + "payload": get_started_payload + } + ], + "access_token": configuration.access_token + } + + request({ + method: 'POST', + json: true, + headers: { + 'content-type': 'application/json', + }, + body: get_started_message, + uri: 'https://graph.facebook.com/v2.6/me/thread_settings' + }, + function(err, res, body) { + + if (err) { + botkit.debug('WEBHOOK ERROR', err); + return cb && cb(err); + } + + if (body.error) { + botkit.debug('API ERROR', body.error); + return cb && cb(body.error.message); + } + + botkit.debug('WEBHOOK SUCCESS', body); + cb && cb(null, body); + }); + } + + // Setup a handler to delete the payload for Get Started button + bot.deleteGetStartedPayload = function(cb) { + delete_get_started_message = { + "setting_type":"call_to_actions", + "thread_state":"new_thread", + "access_token": configuration.access_token + } + + request({ + method: 'DELETE', + json: true, + headers: { + 'content-type': 'application/json', + }, + body: delete_get_started_message, + uri: 'https://graph.facebook.com/v2.6/me/thread_settings' + }, + function(err, res, body) { + if (err) { + botkit.debug('WEBHOOK ERROR', err); + return cb && cb(err); + } + + if (body.error) { + botkit.debug('API ERROR', body.error); + return cb && cb(body.error.message); + } + + botkit.debug('WEBHOOK SUCCESS', body); + cb && cb(null, body); + }); + } + return bot; }); diff --git a/readme-facebook.md b/readme-facebook.md index 561bdd0c5..39859836e 100644 --- a/readme-facebook.md +++ b/readme-facebook.md @@ -71,7 +71,7 @@ All incoming events will contain the fields `user` and `channel`, both of which `message_received` events will also contain either a `text` field or an `attachment` field. -`facebook_postback` events will contain a `payload` field. +`facebook_postback` events will contain a `payload` field. Notice also that `facebook_postback` events trigger the `message_received` event as well. That is why messages will have the `type` field as well. When the message is directly from the user (i.e. onlye `message_received` event) `type` will be set to `"user_message"` and when the message is originated in a `facebook_postback` then `type` will be set to `facebook_postback`. @@ -242,6 +242,15 @@ reply_message = { bot.reply(message, reply_message) ``` +## "Get Started" Button + +Facebook Bots have the ability to display a welcome screen before any message is sent. The Welcome Screen can display a Get Started button. When this button is tapped, Facebook will send a postback and in it deliver the person's page-scoped ID (PSID). You can then present a personalized message to greet the user or present buttons to prompt him or her to take an action. + +To use this ability `botkit` exposes two methods on facebook bots + +* `setGetStartedPayload(get_started_payload, callback_function)` - calling this will set `get_started_payload` as the payload (i.e. message) that the user will send as a message when clicking the "Get Started" button on the bot's screen in Facebook. It will also call `callback_function` on the response for the request to set the payload. +* `deleteGetStartedPayload(callback_function)` - calling this will cancel any setting made for the welcome "Get Started" screen for the bot. + ## Use BotKit for Facebook Messenger with an Express web server Instead of the web server generated with setupWebserver(), it is possible to use a different web server to receive webhooks, as well as serving web pages.