fb-messenger 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +109 -28
  3. data/fb-messenger.gemspec +2 -2
  4. data/lib/fb/messenger/version.rb +1 -1
  5. metadata +5 -4
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: ef3e88424f5141101e430387f7ba07a9a25e018e
4
- data.tar.gz: 210408a593972d4885fc7eccf1192a6c1e471408
3
+ metadata.gz: 483b46da70b49ab85ce2f3b79c379668e965ee46
4
+ data.tar.gz: 4f1389072eeed41c6baf5d487f400526cea38d7e
5
5
  SHA512:
6
- metadata.gz: 639d872286b914e593480788730d67e730d21d01f498878da9378b10717a9502b4c4c1a0bd5d959ffd49b1b20b41fe0b63b0fdd176138714aa009bfbf3ac219e
7
- data.tar.gz: 0279a3ba2119cb0a219e325316683fbc96a361489b9ecbfc19efc4e2155a74e3fd3411077ab50eb285c54955e4593b21e5c2c14fed31a87dff3495c73a590ce9
6
+ metadata.gz: 6bd896f134d74bf84f63c45bc3f50ada30c4ded9ea497ac34c26256dc9024bb0991e89ba64bf3691a9cb90c229899db70f229e9217a4dd763ff9acaea3da4b62
7
+ data.tar.gz: b22646e7286eb2e22957385b7d2d3b846bfc583d05b56ab1ee717974e39d14218cceba45c2458f0a4a1e21d486e336c6e4a2aeb926eff717659a33b246a390dc
data/README.md CHANGED
@@ -1,38 +1,119 @@
1
- # Fb::Messenger
2
-
3
- Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/fb/messenger`. To experiment with that code, run `bin/console` for an interactive prompt.
4
-
5
- TODO: Delete this and the text above, and describe your gem
6
-
7
- ## Installation
8
-
9
- Add this line to your application's Gemfile:
1
+ # Overview
2
+
3
+ This gem uses the [Facebook Messenger API](https://developers.facebook.com/docs/messenger-platform/send-api-reference) to send and receive Facebook messages. Note that you will need to configure a [webhook URL](https://developers.facebook.com/docs/messenger-platform/webhook-reference) in your web app to which facebook messages will be posted. Please go through the [getting started guide](https://developers.facebook.com/docs/messenger-platform/quickstart) for setting up Facebook Messenger API, which is a pre-requisite step for using this gem.
4
+
5
+ # Usage
6
+
7
+ ## Receiving Messages
8
+
9
+ The following steps uses a rails setup, but the gem can be used in any ruby web framework that is capable of creating an API endpoint for the configured webhook.
10
+
11
+ 1. Add the following to an initializer `config/initializers/<name>.rb` to setup your [fb access token](https://developers.facebook.com/docs/messenger-platform/quickstart) and [fb verify token](https://developers.facebook.com/docs/messenger-platform/quickstart)
12
+ ```ruby
13
+ require 'fb/messenger'
14
+
15
+ Fb::Messenger.configure do |config|
16
+ config.access_token = 'FB_MESSENGER_ACCESS_TOKEN'
17
+ config.verify_token = 'FB_MESSENGER_VERIFY_TOKEN'
18
+ end
19
+ ```
20
+
21
+ 2. Ensure that you have subscribers for each of the messenger [webhook events](https://developers.facebook.com/docs/messenger-platform/webhook-reference), namely 'message', 'postback', and 'deliver', e.g., add the following to the same `config/initializers/<name>.rb` file:
22
+ ```ruby
23
+ Fb::Messenger::Receiver.configure do |receiver|
24
+ receiver.subscribe 'message', MsgSubscriber.new
25
+ receiver.subscribe 'postback', PostBackSubscriber.new
26
+ receiver.subscribe 'delivery', DeliverySubscriber.new
27
+ end
28
+ ```
29
+
30
+ Where the classes `MsgSubscriber`, `PostBackSubscriber`, and `DeliverSubscriber` (arbitary class names) implements a `call` method seen in [Fb::Messenger::Subscriber::Base](https://github.com/ccleung/fb-messenger/blob/master/lib/fb/messenger/subscribers/base.rb)
31
+
32
+ Usually in the `call` method, you would use the [Fb::Messenger::Client](https://github.com/ccleung/fb-messenger/blob/master/README.md#sending-messages) to create reply message back to the sender.
33
+
34
+ 3. In `routes.rb` specify two endpoints, one for verifying the webhook and one for handling webhook POST requests, e.g.,
35
+ ```ruby
36
+ Rails.application.routes.draw do
37
+ get 'facebook/webhook' => 'facebook#verify'
38
+ post 'facebook/webhook' => 'facebook#webhook'
39
+ end
40
+ ```
41
+
42
+ 4. In the corresponding controller that implements the webhook add the following:
43
+ ```ruby
44
+ def webhook
45
+ Fb::Messenger::Receiver.receive(params[:entry])
46
+ head 200
47
+ end
48
+ ```
49
+
50
+ Note that you need to return 2XX to indicate that you have received the message. To implement the `verify` controller action method for this example, please see the fb messenger [getting started guide](https://developers.facebook.com/docs/messenger-platform/quickstart).
51
+
52
+ ## Sending Messages
53
+
54
+ The `Fb::Messenger::Client` is used for sending fb messages. In the following examples, `id` can represent different types of facebook id's, such as page id's or user id's (see: https://developers.facebook.com/docs/messenger-platform/send-api-reference). Note that the `Fb::Messenger::Client` can be used in your subscriber `call` methods to reply back to messages.
55
+
56
+ Send [Text Messages](https://developers.facebook.com/docs/messenger-platform/send-api-reference/text-message):
10
57
 
11
58
  ```ruby
12
- gem 'fb-messenger'
59
+ Fb::Messenger::Client.send_message_text(id, "your message here")
13
60
  ```
14
61
 
15
- And then execute:
16
-
17
- $ bundle
18
-
19
- Or install it yourself as:
20
-
21
- $ gem install fb-messenger
22
-
23
- ## Usage
62
+ Send [Generic Template Messages](https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template):
24
63
 
25
- TODO: Write usage instructions here
26
-
27
- ## Development
28
-
29
- After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
30
-
31
- To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
64
+ ```ruby
65
+ item = Fb::Messenger::Template::GenericItem.new
66
+ # assign values to each attribute
67
+ item.title = 'title'
68
+ item.subtitle = '...'
69
+ item.image_url = '...'
70
+
71
+ button = Fb::Messenger::Template::Button.new
72
+ # see: https://developers.facebook.com/docs/messenger-platform/send-api-reference/button-template
73
+ button.type = 'postback'
74
+ button.title = '...'
75
+ # this can be a json string that your Subscriber for postback must handle
76
+ button.payload = '...'
77
+
78
+ # you can add multiple buttons
79
+ item.buttons << button
80
+
81
+ generic = Fb::Messenger::Template::Generic
82
+ # you can add multiple generic items
83
+ generic.generic_items << item
84
+
85
+ template_msg = generic.template
86
+ Fb::Messenger::Client.send_message_template(id, template_msg)
87
+ ```
32
88
 
33
- ## Contributing
89
+ Send [Receipt Template Messages](https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template):
34
90
 
35
- Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/fb-messenger.
91
+ ```ruby
92
+ item = Fb::Messenger::Template::ReceiptItem.new
93
+ item.title = 'title'
94
+ item.subtitle = '...'
95
+ item.quantity = '...'
96
+ item.price = '...'
97
+ item.currency = '...'
98
+ item.image_url = '...'
99
+
100
+ receipt = Fb::Messenger::Template::Receipt.new
101
+
102
+ # Please see https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template for example values
103
+ receipt.recipient_name = '...'
104
+ receipt.order_number = '...'
105
+ receipt.currency = '...'
106
+ # payment_method cannot be nil
107
+ receipt.payment_method = '...'
108
+ receipt.order_url = '...'
109
+ receipt.timestamp = '...'
110
+ receipt.total_cost = '...'
111
+ # can add multiple items
112
+ receipt.receipt_items << item
113
+
114
+ template_msg = receipt.template
115
+ Fb::Messenger::Client.send_message_template(id, template_msg)
116
+ ```
36
117
 
37
118
 
38
119
  ## License
data/fb-messenger.gemspec CHANGED
@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
9
9
  spec.authors = ["ccleung"]
10
10
  spec.email = ["clemsquared@gmail.com"]
11
11
 
12
- spec.summary = %q{Send and receive Fb messenger messages.}
13
- spec.description = %q{Send and receive Fb messenger messages.}
12
+ spec.summary = %q{Send and receive Facebook messenger messages.}
13
+ spec.description = %q{Send and receive Facebook messenger messages using the Facebook messenger API.}
14
14
  spec.homepage = "https://github.com/ccleung/fb-messenger"
15
15
  spec.license = "MIT"
16
16
 
data/lib/fb/messenger/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  module Fb
2
2
  module Messenger
3
- VERSION = "0.1.0"
3
+ VERSION = "0.1.1"
4
4
  end
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: fb-messenger
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.1.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - ccleung
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2016-07-13 00:00:00.000000000 Z
11
+ date: 2016-07-31 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: rest-client
@@ -94,7 +94,8 @@ dependencies:
94
94
  - - "~>"
95
95
  - !ruby/object:Gem::Version
96
96
  version: '2.1'
97
- description: Send and receive Fb messenger messages.
97
+ description: Send and receive Facebook messenger messages using the Facebook messenger
98
+ API.
98
99
  email:
99
100
  - clemsquared@gmail.com
100
101
  executables: []
@@ -149,5 +150,5 @@ rubyforge_project:
149
150
  rubygems_version: 2.4.5.1
150
151
  signing_key:
151
152
  specification_version: 4
152
- summary: Send and receive Fb messenger messages.
153
+ summary: Send and receive Facebook messenger messages.
153
154
  test_files: []