facebook-messenger 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d44d493f7a90af8ada14c7bdcece0b54fa033abf
-  data.tar.gz: 5299267b035cda79e916beb6752fc736c9ec9853
+  metadata.gz: 4eb152a59edb50fe9a410f715d347c58a1ecee2e
+  data.tar.gz: 0832b222a0ce2e352c191dd4797760d5b5f1871e
 SHA512:
-  metadata.gz: 5707bbee02a68b2bf370d841d8644c7b6bdd2acadbcc93083c0c76743d337e1aad126c731a2374a92b064e233a4bd8e1f02df7d1f958700ea81c084b04ccff63
-  data.tar.gz: 4db0e0fcd018f909478a98162275bbc91691a81ac1c40106ecec4eb0c2f4e276b16c1598713e6fbfcbadb580b212f2fa85266f1e66e4ca551749b7b6a9244909
+  metadata.gz: a47da0222b108ffb19ffc5e28f730474deb7ebe1ee0fb32ec6e00ca66fa6a69550ef8221f4277da77241d2d38b31744b40a3dc22fea4dec03b9e14f0dbc2519f
+  data.tar.gz: 2e5ddec2fc4ea8dfd22d77de20dd364121cbe4def6b06f707d7917e9f73ec57dc83a455b6b762ade18b5551583a57a128e3335ea71634555514858ff763dad4a

data/README.md

@@ -8,7 +8,7 @@
 [![Dependency Status](https://img.shields.io/gemnasium/hyperoslo/facebook-messenger.svg?style=flat)](https://gemnasium.com/hyperoslo/facebook-messenger)
 [![Code Climate](https://img.shields.io/codeclimate/github/hyperoslo/facebook-messenger.svg?style=flat)](https://codeclimate.com/github/hyperoslo/facebook-messenger)
 [![Coverage Status](https://img.shields.io/coveralls/hyperoslo/facebook-messenger.svg?style=flat)](https://coveralls.io/r/hyperoslo/facebook-messenger)
-[![Join the chat at https://gitter.im/hyperoslo/facebook-messenger](https://badges.gitter.im/hyperoslo/facebook-messenger.svg)](https://gitter.im/hyperoslo/facebook-messenger?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Documentation Coverage](http://inch-ci.org/github/jgorset/facebook-messenger.svg?branch=master)](http://inch-ci.org/github/jgorset/facebook-messenger)
 
 ## Installation
 
@@ -47,7 +47,8 @@ Bot.deliver({
   },
   message: {
     text: 'Human?'
-  }
+  },
+  message_type: Facebook::Messenger::Bot::MessagingType::UPDATE
 }, access_token: ENV['ACCESS_TOKEN'])
 ```
 
@@ -171,10 +172,21 @@ Bot.on :message_echo do |message_echo|
   message_echo.text        # => 'Hello, bot!'
   message_echo.attachments # => [ { 'type' => 'image', 'payload' => { 'url' => 'https://www.example.com/1.jpg' } } ]
 
-  # Log or store in your storage method of choice.
+  # Log or store in your storage method of choice (skynet, obviously)
 end
 ```
 
+##### Record accepted message requests
+
+You can keep track of message requests accepted by the human:
+
+```ruby
+Bot.on :message_request do |message_request|
+  message_request.accept? # => true
+
+  # Log or store in your storage method of choice (skynet, obviously)
+end
+```
 
 #### Send to Facebook
 
@@ -266,7 +278,7 @@ Facebook::Messenger::Profile.set({
           type: 'nested',
           call_to_actions: [
             {
-              title: 'What's a chatbot?',
+              title: 'What is a chatbot?',
               type: 'postback',
               payload: 'EXTERMINATE'
             },
@@ -298,6 +310,53 @@ Facebook::Messenger::Profile.set({
 }, access_token: ENV['ACCESS_TOKEN'])
 ```
 
+
+#### Handle a Facebook Policy Violation
+
+See Facebook's documentation on [Messaging Policy Enforcement](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_policy_enforcement)
+
+```ruby
+Bot.on :'policy_enforcement' do |referral|
+  referral.action # => 'block'
+  referral.reason # => "The bot violated our Platform Policies (https://developers.facebook.com/policy/#messengerplatform). Common violations include sending out excessive spammy messages or being non-functional."
+end
+```
+#### messaging_type
+##### Sending Messages
+See Facebook's documentation on [Sending Messages](https://developers.facebook.com/docs/messenger-platform/send-messages#standard_messaging)
+
+As of May 7th 2018 all messages are required to include a messaging_type
+
+```ruby
+Bot.deliver({
+  recipient: {
+    id: '45123'
+  },
+  message: {
+    text: 'Human?'
+  },
+  message_type: Facebook::Messenger::Bot::MessagingType::UPDATE
+}, access_token: ENV['ACCESS_TOKEN'])
+```
+
+##### MESSAGE_TAG
+See Facebook's documentation on [Message Tags](https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags)
+
+When sending a message with messaging_type: MESSAGE_TAG (Facebook::Messenger::Bot::MessagingType::MESSAGE_TAG) you must ensure you add a tag: parameter
+
+```ruby
+Bot.deliver({
+  recipient: {
+    id: '45123'
+  },
+  message: {
+    text: 'Human?'
+  },
+  message_type: Facebook::Messenger::Bot::MessagingType::MESSAGE_TAG
+  tag: Facebook::Messenger::Bot::Tag::NON_PROMOTIONAL_SUBSCRIPTION
+}, access_token: ENV['ACCESS_TOKEN'])
+```
+
 ## Configuration
 
 ### Create an Application on Facebook
@@ -324,16 +383,36 @@ to keep track of access tokens, app secrets and verify tokens for each of them:
 
 ```ruby
 class ExampleProvider < Facebook::Messenger::Configuration::Providers::Base
+  # Verify that the given verify token is valid.
+  #
+  # verify_token - A String describing the application's verify token.
+  #
+  # Returns a Boolean representing whether the verify token is valid.
   def valid_verify_token?(verify_token)
     bot.exists?(verify_token: verify_token)
   end
 
+  # Find the right application secret.
+  #
+  # page_id - An Integer describing a Facebook Page ID.
+  #
+  # Returns a String describing the application secret.
   def app_secret_for(page_id)
     bot.find_by(page_id: page_id).app_secret
   end
 
-  def access_token_for(page_id)
-    bot.find_by(page_id: page_id).access_token
+  # Find the right access token.
+  #
+  # recipient - A Hash describing the `recipient` attribute of the message coming
+  #             from Facebook.
+  #
+  # Note: The naming of "recipient" can throw you off, but think of it from the
+  # perspective of the message: The "recipient" is the page that receives the
+  # message.
+  #
+  # Returns a String describing an access token.
+  def access_token_for(recipient)
+    bot.find_by(page_id: recipient['id']).access_token
   end
 
   private
@@ -375,6 +454,8 @@ require 'facebook/messenger'
 require_relative 'bot'
 
 run Facebook::Messenger::Server
+
+# or Facebook::Messenger::ServerNoError for dev
 ```
 
 ```
@@ -437,9 +518,64 @@ config.paths.add File.join('app', 'bot'), glob: File.join('**', '*.rb')
 config.autoload_paths += Dir[Rails.root.join('app', 'bot', '*')]
 ```
 
+
+### Test it...
+
+##### ...locally
 To test your locally running bot, you can use [ngrok]. This will create a secure
 tunnel to localhost so that Facebook can reach the webhook.
 
+##### ... with RSpec
+
+In order to test that behaviour when a new event from Facebook is registered, you can use the gem's `trigger` method. This method accepts as its first argument the type of event that it will receive, and can then be followed by other arguments that mock objects received from Messenger. Using Ruby's [Struct](https://ruby-doc.org/core-2.5.0/Struct.html) class can be very useful for creating these mock objects.
+
+In this case, subscribing to Messenger events has been extracted into a `Listener` class.   
+```ruby
+# app/bot/listener.rb
+require 'facebook/messenger'
+
+include Facebook::Messenger
+
+class Listener
+  Facebook::Messenger::Subscriptions.subscribe(access_token: ENV["FB_ACCESS_TOKEN"])
+
+  Bot.on :message do |message|
+    Bot.deliver({
+      recipient: message.sender,
+      message: {
+        text: 'Uploading your message to skynet.'
+      }
+    }, access_token: ENV['FB_ACCESS_TOKEN'])
+  end
+end
+```
+Its respective test file then ensures that the `Bot` object receives a call to `deliver`. This is just a basic test, but check out the [RSpec docs](http://rspec.info/) for more information on testing with RSpec.
+```ruby
+require 'rails_helper'
+
+RSpec.describe Listener do
+  FakeMessage = Struct.new(:sender, :recipient, :timestamp, :message)
+
+  describe 'Bot#on(message)' do
+    it 'responds with a message' do
+      expect(Bot).to receive(:deliver)
+      Bot.trigger(:message, fake_message)
+    end
+  end
+
+  private
+
+  def fake_message
+    sender = {"id"=>"1234"}
+    recipient = {"id"=>"5678"}
+    timestamp = 1528049653543
+    message = {"text"=>"Hello, world"}
+    FakeMessage.new(sender, recipient, timestamp, message)
+  end
+end
+```
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run
@@ -467,11 +603,16 @@ support bots with, well, Facebook Messenger.
 
 * [Botamp](https://botamp.com) is the all-in-one solution for Marketing Automation via messaging apps.
 
-## Hyper loves you
+## I love you
+
+Johannes Gorset made this. You should [tweet me](http://twitter.com/jgorset) if you can't get it
+to work. In fact, you should tweet me anyway.
+
+## I love Schibsted
 
-[Hyper] made this. We're a bunch of folks who love building things. You should
-[tweet us] if you can't get it to work. In fact, you should tweet us anyway.
-If you're using Facebook Messenger, we probably want to [hire you].
+I work at [Schibsted Products & Technology](https://github.com/schibsted) with a bunch of awesome folks
+who are every bit as passionate about building things as I am. If you're using Facebook Messenger,
+you should probably join us.
 
 [Hyper]: https://github.com/hyperoslo
 [tweet us]: http://twitter.com/hyperoslo

data/lib/facebook/messenger.rb

@@ -4,6 +4,7 @@ require 'facebook/messenger/subscriptions'
 require 'facebook/messenger/profile'
 require 'facebook/messenger/bot'
 require 'facebook/messenger/server'
+require 'facebook/messenger/server_no_error'
 require 'facebook/messenger/configuration'
 require 'facebook/messenger/incoming'
 
@@ -22,6 +23,8 @@ module Facebook
       @config = config
     end
 
+    # Set the default configuration provider.
+    # Developer can set different configuration provider.
     configure do |config|
       config.provider = Configuration::Providers::Environment.new
     end

data/lib/facebook/messenger/bot.rb

@@ -1,14 +1,20 @@
 require 'facebook/messenger/bot/error_parser'
 require 'facebook/messenger/bot/exceptions'
+require 'facebook/messenger/bot/message_type'
 
 module Facebook
   module Messenger
-    # The Bot module sends and receives messages.
+    #
+    # Module Bot provides functionality to sends and receives messages.
+    #
     module Bot
       include HTTParty
 
-      base_uri 'https://graph.facebook.com/v2.6/me'
+      # Define base_uri for HTTParty.
+      base_uri 'https://graph.facebook.com/v2.9/me'
 
+      #
+      # @return [Array] Array containing the supported webhook events.
       EVENTS = %i[
         message
         delivery
@@ -18,14 +24,19 @@ module Facebook
         account_linking
         referral
         message_echo
+        payment
+        policy_enforcement
       ].freeze
 
       class << self
         # Deliver a message with the given payload.
+        # @see https://developers.facebook.com/docs/messenger-platform/send-api-reference#request
         #
-        # message - A Hash describing the recipient and the message*.
+        # @raise [Facebook::Messenger::Bot::SendError] if there is any error
+        #   in response while sending message.
         #
-        # * https://developers.facebook.com/docs/messenger-platform/send-api-reference#request
+        # @param [Hash] message A Hash describing the recipient and the message.
+        # @param [String] access_token Access token.
         #
         # Returns a String describing the message ID if the message was sent,
         # or raises an exception if it was not.
@@ -44,8 +55,12 @@ module Facebook
 
         # Register a hook for the given event.
         #
-        # event - A String describing a Messenger event.
-        # block - A code block to run upon the event.
+        # @raise [ArgumentError] if received event is not registered.
+        #
+        # @param [String] event A String describing a Messenger event.
+        # @param [Block] block A code block to run upon the event.
+        #
+        # @return Save event and its block in hooks.
         def on(event, &block)
           unless EVENTS.include? event
             raise ArgumentError,
@@ -58,9 +73,12 @@ module Facebook
 
         # Receive a given message from Messenger.
         #
-        # payload - A Hash describing the message.
+        # @see https://developers.facebook.com/docs/messenger-platform/webhook-reference
+        #
+        # @param [Hash] payload A Hash describing the message.
+        #
+        # @return pass event and object of callback class to trigger function.
         #
-        # * https://developers.facebook.com/docs/messenger-platform/webhook-reference
         def receive(payload)
           callback = Facebook::Messenger::Incoming.parse(payload)
           event = Facebook::Messenger::Incoming::EVENTS.invert[callback.class]
@@ -68,26 +86,41 @@ module Facebook
         end
 
         # Trigger the hook for the given event.
+        # Fetch callback for event from hooks and call it.
         #
-        # event - A String describing a Messenger event.
-        # args - Arguments to pass to the hook.
+        # @raise [KeyError] if hook is not registered for event
+        #
+        # @param [String] event A String describing a Messenger event.
+        # @param [Object] args Arguments to pass to the hook.
         def trigger(event, *args)
           hooks.fetch(event).call(*args)
         rescue KeyError
           $stderr.puts "Ignoring #{event} (no hook registered)"
         end
 
+        #
         # Return a Hash of hooks.
+        #
+        # @return [Hash] Hash of hooks.
+        #
         def hooks
           @hooks ||= {}
         end
 
+        #
         # Deregister all hooks.
+        #
+        # @return [Hash] Assign empty hash to hooks and return it.
+        #
         def unhook
           @hooks = {}
         end
 
+        #
         # Default HTTParty options.
+        #
+        # @return [Hash] Default HTTParty options.
+        #
         def default_options
           super.merge(
             read_timeout: 300,

data/lib/facebook/messenger/bot/message_type.rb

@@ -0,0 +1,13 @@
+module Facebook
+  module Messenger
+    module Bot
+      # Supported message types
+      module MessageType
+        RESPONSE = 'RESPONSE'.freeze
+        UPDATE = 'UPDATE'.freeze
+        MESSAGE_TAG = 'MESSAGE_TAG'.freeze
+        NON_PROMOTIONAL_SUBSCRIPTION = 'NON_PROMOTIONAL_SUBSCRIPTION'.freeze
+      end
+    end
+  end
+end

data/lib/facebook/messenger/bot/messaging_type.rb

@@ -0,0 +1,12 @@
+module Facebook
+  module Messenger
+    module Bot
+      # Supported message types
+      module MessagingType
+        RESPONSE = 'RESPONSE'.freeze
+        UPDATE = 'UPDATE'.freeze
+        MESSAGE_TAG = 'MESSAGE_TAG'.freeze
+      end
+    end
+  end
+end

data/lib/facebook/messenger/bot/tag.rb

@@ -0,0 +1,27 @@
+module Facebook
+  module Messenger
+    module Bot
+      # Supported tags.
+      # Note: A tag is required when sending messages with the
+      # message type `MESSAGE_TAG`.
+      module Tag
+        COMMUNITY_ALERT               = 'COMMUNITY_ALERT'.freeze
+        CONFIRMED_EVENT_REMINDER      = 'CONFIRMED_EVENT_REMINDER'.freeze
+        NON_PROMOTIONAL_SUBSCRIPTION  = 'NON_PROMOTIONAL_SUBSCRIPTION'.freeze
+        PAIRING_UPDATE                = 'PAIRING_UPDATE'.freeze
+        APPLICATION_UPDATE            = 'APPLICATION_UPDATE'.freeze
+        ACCOUNT_UPDATE                = 'ACCOUNT_UPDATE'.freeze
+        PAYMENT_UPDATE                = 'PAYMENT_UPDATE'.freeze
+        PERSONAL_FINANCE_UPDATE       = 'PERSONAL_FINANCE_UPDATE'.freeze
+        SHIPPING_UPDATE               = 'SHIPPING_UPDATE'.freeze
+        RESERVATION_UPDATE            = 'RESERVATION_UPDATE'.freeze
+        ISSUE_RESOLUTION              = 'ISSUE_RESOLUTION'.freeze
+        APPOINTMENT_UPDATE            = 'APPOINTMENT_UPDATE'.freeze
+        GAME_EVENT                    = 'GAME_EVENT'.freeze
+        TRANSPORTATION_UPDATE         = 'TRANSPORTATION_UPDATE'.freeze
+        FEATURE_FUNCTIONALITY_UPDATE  = 'FEATURE_FUNCTIONALITY_UPDATE'.freeze
+        TICKET_UPDATE                 = 'TICKET_UPDATE'.freeze
+      end
+    end
+  end
+end

data/lib/facebook/messenger/configuration.rb

@@ -2,7 +2,9 @@ require 'facebook/messenger/configuration/providers'
 
 module Facebook
   module Messenger
-    # This module holds the configuration.
+    #
+    # Class Configuration holds the configuration for bot.
+    #
     class Configuration
       attr_accessor :provider
     end