Merge pull request #470 from agamrafaeli/issue-372

Add handlers for setting and deleting the Get Started payload

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;
 
     });

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.