Merge pull request #51 from sorich87/feature/thread-settings

Add thread settings

README.md

@@ -155,12 +155,58 @@ Bot.on :delivery do |delivery|
 end
 ```
 
-#### Set a welcome message
+#### Change thread settings
 
 You can greet new humans to entice them into talking to you:
 
 ```ruby
-Facebook::Messenger::Welcome.set text: 'Hello, human!'
+Facebook::Messenger::Thread.set(
+  setting_type: 'greeting',
+  greeting: {
+    text: 'Welcome to your new bot overlord!'
+  }
+)
+```
+
+You can define the action to trigger when new humans click on the Get
+Started button.
+
+```ruby
+Facebook::Messenger::Thread.set(
+  setting_type: 'call_to_actions',
+  thread_state: 'new_thread',
+  call_to_actions: [
+    {
+      payload: 'DEVELOPER_DEFINED_PAYLOAD_FOR_WELCOME'
+    }
+  ]
+)
+```
+
+You can show a persistent menu to humans.
+
+```ruby
+Facebook::Messenger::Thread.set(
+  setting_type: 'call_to_actions',
+  thread_state: 'existing_thread',
+  call_to_actions: [
+    {
+      type: 'postback',
+      title: 'Help',
+      payload: 'DEVELOPER_DEFINED_PAYLOAD_FOR_HELP'
+    },
+    {
+      type: 'postback',
+      title: 'Start a New Order',
+      payload: 'DEVELOPER_DEFINED_PAYLOAD_FOR_START_ORDER'
+    },
+    {
+      type: 'web_url',
+      title: 'View Website',
+      url: 'http://example.com/'
+    }
+  ]
+)
 ```
 
 ## Configuration

lib/facebook/messenger.rb

@@ -1,7 +1,7 @@
 require 'facebook/messenger/version'
 require 'facebook/messenger/error'
 require 'facebook/messenger/subscriptions'
-require 'facebook/messenger/welcome'
+require 'facebook/messenger/thread'
 require 'facebook/messenger/bot'
 require 'facebook/messenger/server'
 require 'facebook/messenger/configuration'

lib/facebook/messenger/welcome.rb → lib/facebook/messenger/thread.rb

@@ -2,10 +2,10 @@
 
 module Facebook
   module Messenger
-    # This module handles setting welcome messages.
+    # This module handles changing thread settings.
     #
-    # https://developers.facebook.com/docs/messenger-platform/send-api-reference#welcome_message_configuration
-    module Welcome
+    # https://developers.facebook.com/docs/messenger-platform/thread-settings
+    module Thread
       include HTTParty
 
       base_uri 'https://graph.facebook.com/v2.6/me'
@@ -14,18 +14,18 @@ module Welcome
 
       module_function
 
-      def set(message)
+      def set(settings)
         response = post '/thread_settings',
-                        body: welcome_setting_for(message).to_json
+                        body: settings.to_json
 
         raise_errors(response)
 
         true
       end
 
-      def unset
-        response = post '/thread_settings',
-                        body: welcome_setting_for(nil).to_json
+      def unset(settings)
+        response = delete '/thread_settings',
+                          body: settings.to_json
 
         raise_errors(response)
 
@@ -47,14 +47,6 @@ def default_options
         )
       end
 
-      def welcome_setting_for(payload)
-        {
-          setting_type: 'call_to_actions',
-          thread_state: 'new_thread',
-          call_to_actions: payload ? [{ message: payload }] : []
-        }
-      end
-
       class Error < Facebook::Messenger::Error; end
     end
   end

spec/facebook/messenger/welcome_spec.rb → spec/facebook/messenger/thread_spec.rb

@@ -1,10 +1,10 @@
 require 'spec_helper'
 
-describe Facebook::Messenger::Welcome do
+describe Facebook::Messenger::Thread do
   let(:access_token) { '<access token>' }
 
   let(:thread_settings_url) do
-    Facebook::Messenger::Welcome.base_uri + '/thread_settings'
+    Facebook::Messenger::Thread.base_uri + '/thread_settings'
   end
 
   before do
@@ -27,13 +27,7 @@
             body: JSON.dump(
               setting_type: 'call_to_actions',
               thread_state: 'new_thread',
-              call_to_actions: [
-                {
-                  message: {
-                    text: 'Hello, human!'
-                  }
-                }
-              ]
+              call_to_actions: [{ payload: 'USER_DEFINED_PAYLOAD' }]
             )
           )
           .to_return(
@@ -46,7 +40,13 @@
       end
 
       it 'returns true' do
-        expect(subject.set(text: 'Hello, human!')).to be(true)
+        expect(
+          subject.set(
+            setting_type: 'call_to_actions',
+            thread_state: 'new_thread',
+            call_to_actions: [{ payload: 'USER_DEFINED_PAYLOAD' }]
+          )
+        ).to be(true)
       end
     end
 
@@ -71,8 +71,14 @@
       end
 
       it 'raises an error' do
-        expect { subject.set text: 'Hello, human!' }.to raise_error(
-          Facebook::Messenger::Welcome::Error, error_message
+        expect do
+          subject.set(
+            setting_type: 'call_to_actions',
+            thread_state: 'new_thread',
+            call_to_actions: [{ payload: 'USER_DEFINED_PAYLOAD' }]
+          )
+        end.to raise_error(
+          Facebook::Messenger::Thread::Error, error_message
         )
       end
     end
@@ -81,7 +87,7 @@
   describe '.unset' do
     context 'with a successful response' do
       before do
-        stub_request(:post, thread_settings_url)
+        stub_request(:delete, thread_settings_url)
           .with(
             query: {
               access_token: access_token
@@ -91,8 +97,7 @@
             },
             body: JSON.dump(
               setting_type: 'call_to_actions',
-              thread_state: 'new_thread',
-              call_to_actions: []
+              thread_state: 'new_thread'
             )
           )
           .to_return(
@@ -105,15 +110,20 @@
       end
 
       it 'returns true' do
-        expect(subject.unset).to be(true)
+        expect(
+          subject.unset(
+            setting_type: 'call_to_actions',
+            thread_state: 'new_thread'
+          )
+        ).to be(true)
       end
     end
 
     context 'with an unsuccessful response' do
       let(:error_message) { 'Invalid OAuth access token.' }
 
       before do
-        stub_request(:post, thread_settings_url)
+        stub_request(:delete, thread_settings_url)
           .with(query: { access_token: access_token })
           .to_return(
             body: JSON.dump(
@@ -130,8 +140,13 @@
       end
 
       it 'raises an error' do
-        expect { subject.unset }.to raise_error(
-          Facebook::Messenger::Welcome::Error, error_message
+        expect do
+          subject.unset(
+            setting_type: 'call_to_actions',
+            thread_state: 'new_thread'
+          )
+        end.to raise_error(
+          Facebook::Messenger::Thread::Error, error_message
         )
       end
     end