Ruby on Rails Gem for Facebook Messenger Platform integration
Ruby HTML CSS JavaScript
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Messenger Platform Rails

Gem Version Code Climate Build Status

## Description

Messenger Platform Rails aims to be a complete solution for integrating the Facebook Messenger Platform to your Rails application.

Currently it provides following capabilities:

  • Respond to Facebook Webhook verification challenge
  • Subscribe App to a Page
  • Receive text messages
  • Receive messages with attachments
  • Send text messages to users
  • Send images to users


Install the Gem

Add to your Gemfile

gem "messenger_platform_rails"

Mount the engine

Mount in your config/routes.rb

mount MessengerPlatform::Engine, at: "/hookie_hook"

This will mount the following routes in your application:

Path Verb Usage
/hookie_hook GET Used for initial verification when setting up the webhook urls
/hookie_hook POST Used for receiving incoming messages


Configure using an initializer such as config/initializers/messenger_platform.rb

MessengerPlatform.setup do |config|
    config.verify_token = '<YOUR VERIFICATION TOKEN>`
    config.access_token = '<YOUR ACCESS TOKEN>'
    config.processor_class = MessageProcessor
    config.processor_method = :do_thing
Option Usage
verify_token Used for initial verification during webhook setup
access_token Page Access Token used for subscription rake task and for sending messages
processor_class Class to be initialized with an instance of MessengerPlatform::InboundMessage
processor_method Method to call on the processor_class instance to process the message, default is :process


Verify Webhook

The gem provides an endpoint that will respond correctly to the verification challenge set by the Facebook Webhook configuration dialog using the values set in your configuration

Subscribing the App to the Page

The gem includes a convenience rake task to create the appropriate subscription using the Page Access token from your configuration.

rake messenger_platform:subscribe

Example Processor Class

You can now create your own processor class as per your configuration

class MessageProcessor
    def initialize(message)
        @message = message
    def do_thing
        # This gets invoked whenever a message is received

The message argument received is of type MessengerPlatform::InboundMessage

InboundMessage class

InboundMessage class contains parsed and raw data of the message received. It contains the following attributes

Attribute Example Explanation
sender MessengerPlatform::Contact Sender of message
recipient MessengerPlatform::Contact Recipient of message
timestamp 1458696618911 Timestamp of message
message_id mid.1457764197618:41d102a3e1ae206a38 Message Id
sequence 73 Message Sequence Number
text "Helloo" Text of the message
attachments [ ] Array of MessengerPlatform::Attachment instances

These more or less map directly to the attributes in the official Messenger Platform documentation

The message may contain several attachments, convenience method .attachments? can be used to check for presence of attachments.

Messages with no attachments will respond to .attachments with an empty array.

Contact class

Contact class contains the id and/or phone number of the sender or the recipient.

Attribute Example Explanation
id 123 User ID
phone_number +1(212)555-2368 Users Phone Number

If the contact class contains both id and phone number when serialized for sending messages; the id is preferred over the phone number when present.

Valid Examples{ id: 12312312 }){ phone_number: '+1(212)555-1233' }){ id: 123123, phone_number: '+1(212)555-1233' })

Attachment class

Attachment class contains the type and url of the message attachment as well as several convenience methods for type.

Attribute Example Explanation
type "image" Type of attachment, see below for valid types
url "http://...bunnies.png" URL that can be used to retrieve the attachment

Valid types are image, video and audio, convenience methods image?, video? and audio? can be used to check for the type.

Valid Examples

attachment ={ type: "image", url: "bunnies.png" })

attachment.image? #=> true #=> false
attachment.url #=> "bunnies.png"

TextMessage class

TextMessage class describes a basic message containing plain text to be sent to the user.

Attribute Example Explanation
recipient Instance of Contact class
message "Hello" Text to send in UTF8, max 320 characters
notification_type :silent_push Notification type, default :regular

Valid notification types are regular, silent_push, no_push these map directly to the notification types in the official documentation

To send the message, call the .deliver instance method, this will create the appropriate POST request to Facebook API.

Valid examples

contact ={ id: 12312312 }), "Hello") # => default notification type, "Hi", :silent_push), "Yo", :no_push)

ImageMessage class

ImageMessage class describes an outbound message containing a single image attachment that can be sent to a user.

Attribute Example Explanation
recipient Instance of Contact class
image_url "" URL for the image
notification_type :silent_push Notification type, default :regular

ImageMessages have the same interface as text messages so calling .deliver will send the message


Sending a text message example

contact ={ id: 13123123 })
message = MessengerPlatform::TextMessage(contact, "Hello there")


Sending an image message example

contact ={ id: 13123123 })
message = MessengerPlatform::ImageMessage(contact, "")


Echo service

class MessageService

    def initialize(message)
        @message = message

    def echo
      if @message.text # Some messages are delivery notices without text
        reply =, @message.text)



Semantic versioning ( is used.

For a version number MAJOR.MINOR.PATCH, unless MAJOR is 0:

  1. MAJOR version is incremented when incompatible API changes are made,
  2. MINOR version is incremented when functionality is added in a backwards-compatible manner,
  3. PATCH version is incremented when backwards-compatible bug fixes are made.

Major version "zero" (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable. Furthermore, version "double-zero" (0.0.x) is not intended for public use, as even minimal functionality is not guaranteed to be implemented yet.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request