$ gem install facebook-messenger
You can reply to messages sent by the human:
# bot.rb
require 'facebook/messenger'
include Facebook::Messenger
Bot.on :message do |message|
message.id # => 'mid.1457764197618:41d102a3e1ae206a38'
message.sender # => { 'id' => '1008372609250235' }
message.seq # => 73
message.sent_at # => 2016-04-22 21:30:36 +0200
message.text # => 'Hello, bot!'
message.attachments # => [ { 'type' => 'image', 'payload' => { 'url' => 'https://www.example.com/1.jpg' } } ]
message.reply(text: 'Hello, human!')
end... or even send the human messages out of the blue:
Bot.deliver({
recipient: {
id: '45123'
},
message: {
text: 'Human?'
}
}, access_token: ENV['ACCESS_TOKEN'])The human may require visual aid to understand:
message.reply(
attachment: {
type: 'image',
payload: {
url: 'http://sky.net/visual-aids-for-stupid-organisms/pig.jpg'
}
}
)The human may appreciate hints:
message.reply(
text: 'Human, who is your favorite bot?'
quick_replies: [
{
content_type: 'text',
title: 'You are!',
payload: 'HARMLESS'
}
]
)The human may require simple options to communicate:
message.reply(
attachment: {
type: 'template',
payload: {
template_type: 'button',
text: 'Human, do you like me?',
buttons: [
{ type: 'postback', title: 'Yes', payload: 'HARMLESS' },
{ type: 'postback', title: 'No', payload: 'EXTERMINATE' }
]
}
}
)When the human has selected an option, you can act on it:
Bot.on :postback do |postback|
postback.sender # => { 'id' => '1008372609250235' }
postback.recipient # => { 'id' => '2015573629214912' }
postback.sent_at # => 2016-04-22 21:30:36 +0200
postback.payload # => 'EXTERMINATE'
if postback.payload == 'EXTERMINATE'
puts "Human #{postback.recipient} marked for extermination"
end
endSee Facebook's documentation for all message options.
Show the human you are preparing a message for them:
message.typeWhen the human clicks the Send to Messenger button
embedded on a website, you will receive an optin event.
Bot.on :optin do |optin|
optin.sender # => { 'id' => '1008372609250235' }
optin.recipient # => { 'id' => '2015573629214912' }
optin.sent_at # => 2016-04-22 21:30:36 +0200
optin.ref # => 'CONTACT_SKYNET'
optin.reply(text: 'Ah, human!')
endYou can stalk the human:
Bot.on :delivery do |delivery|
delivery.ids # => 'mid.1457764197618:41d102a3e1ae206a38'
delivery.sender # => { 'id' => '1008372609250235' }
delivery.recipient # => { 'id' => '2015573629214912' }
delivery.at # => 2016-04-22 21:30:36 +0200
delivery.seq # => 37
puts "Human was online at #{delivery.at}"
endWhen the human follows a m.me link with a ref parameter like http://m.me/mybot?ref=myparam,
you will receive a referral event.
Bot.on :referral do |referral|
referral.sender # => { 'id' => '1008372609250235' }
referral.recipient # => { 'id' => '2015573629214912' }
referral.sent_at # => 2016-04-22 21:30:36 +0200
referral.ref # => 'MYPARAM'
endYou can greet new humans to entice them into talking to you:
Facebook::Messenger::Thread.set({
setting_type: 'greeting',
greeting: {
text: 'Welcome to your new bot overlord!'
},
}, access_token: ENV['ACCESS_TOKEN'])You can define the action to trigger when new humans click on the Get Started button. Before doing it you should check to select the messaging_postbacks field when setting up your webhook.
Facebook::Messenger::Thread.set({
setting_type: 'call_to_actions',
thread_state: 'new_thread',
call_to_actions: [
{
payload: 'DEVELOPER_DEFINED_PAYLOAD_FOR_WELCOME'
}
]
}, access_token: ENV['ACCESS_TOKEN'])You can show a persistent menu to humans.
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/'
}
]
}, access_token: ENV['ACCESS_TOKEN'])Create an Application on developers.facebook.com and go to the Messenger tab. Select the Page you want to install your bot on.
Create a new webhook, enter the domain your bot is connected to and a verify token of your choosing.
Note: Don't subscribe to message_echoes; it'll echo your bot's own messages
back to you, effectively DDOSing yourself.
Use the generated access token and your verify token to configure your bot. Most bots live on a single Facebook Page. If that is the case with yours, too, just set these environment variables and skip to the next section:
export ACCESS_TOKEN=EAAAG6WgW...
export APP_SECRET=a885a...
export VERIFY_TOKEN=95vr15g...If your bot lives on multiple Facebook Pages, make a configuration provider to keep track of access tokens, app secrets and verify tokens for each of them:
class ExampleProvider < Facebook::Messenger::Configuration::Providers::Base
def valid_verify_token?(verify_token)
bot.exists?(verify_token: verify_token)
end
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
end
private
def bot
MyApp::Bot
end
end
Facebook::Messenger.configure do |config|
config.provider = ExampleProvider.new
endOnce you've configured your bot, subscribe it to the Page to get messages from Facebook:
Facebook::Messenger::Subscriptions.subscribe(access_token: access_token)The bot runs on Rack, so you hook it up like you would an ordinary web application:
# config.ru
require 'facebook/messenger'
require_relative 'bot'
run Facebook::Messenger::Server$ rackup
Rails doesn't give you much that you'll need for a bot, but if you have an existing application that you'd like to launch it from or just like Rails a lot, you can mount it:
# config/routes.rb
Rails.application.routes.draw do
# ...
mount Facebook::Messenger::Server, at: 'bot'
endWe suggest that you put your bot code in app/bot.
# app/bot/example.rb
include Facebook::Messenger
Bot.on :message do |message|
message.reply(text: 'Hello, human!')
endRemember that Rails only eager loads everything in its production environment.
In the development and test environments, it only requires files as you
reference constants. You'll need to explicitly load app/bot, then:
# config/initializers/bot.rb
unless Rails.env.production?
bot_files = Dir[Rails.root.join('app', 'bot', '**', '*.rb')]
bot_reloader = ActiveSupport::FileUpdateChecker.new(bot_files) do
bot_files.each{ |file| require_dependency file }
end
ActionDispatch::Callbacks.to_prepare do
bot_reloader.execute_if_updated
end
bot_files.each { |file| require_dependency file }
endAnd add below code into config/application.rb to ensure rails knows bot files.
# Auto-load the bot and its subdirectories
config.paths.add File.join('app', 'bot'), glob: File.join('**', '*.rb')
config.autoload_paths += Dir[Rails.root.join('app', 'bot', '*')]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.
After checking out the repo, run bin/setup to install dependencies. You can also run
bin/console for an interactive prompt that will allow you to experiment.
Run rspec to run the tests, rubocop to lint, or rake to do both.
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.
Bug reports and pull requests are welcome on GitHub at https://github.com/hyperoslo/facebook-messenger.
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.