Slack Ruby Bot Server
A library that enables you to write a complete Slack bot service with Slack button integration, in Ruby. If you are not familiar with Slack bots or Slack API concepts, you might want to watch this video. A good demo of a service built on top of this is missingkidsbot.org.
What is this?
A library that contains a Grape API serving a Slack Ruby Bot to multiple teams. This gem combines a web server, a RESTful API and multiple instances of slack-ruby-bot. It integrates with the Slack Platform API. Your customers can use a Slack button to install the bot.
You're reading the documentation for the next release of slack-ruby-bot-server. Please see the documentation for the last stable release, v0.6.1 unless you're integrating with HEAD. See UPGRADING when upgrading from an older version.
Once a bot is registered, you can invite to a channel with
/invite @slackbotserver interact with it. DM "hi" to it, or say "@slackbotserver hi".
Run Your Own
You can use one of the sample applications to bootstrap your project and start adding slack command handlers on top of this code. A database is required to store teams.
Use MongoDB with Mongoid as ODM. Configure the database connection in
mongoid.yml. Add the
mongoid gem in your Gemfile.
gem 'mongoid' gem 'kaminari-mongoid' gem 'mongoid-scroll' gem 'slack-ruby-bot-server'
See the sample app using Mongoid for more information.
Use ActiveRecord with, for example, PostgreSQL via pg. Configure the database connection in
postgresql.yml. Add the
cursor_pagination gems to your Gemfile.
gem 'pg' gem 'activerecord', require: 'active_record' gem 'slack-ruby-bot-server' gem 'otr-activerecord' gem 'cursor_pagination'
See the sample app using ActiveRecord for more information.
Create a New Application on Slack.
Follow the instructions, note the app's client ID and secret, give the bot a default name, etc. The redirect URL should be the location of your app, for testing purposes use
http://localhost:9292. Edit your
.env file and add
SLACK_CLIENT_SECRET=... in it. Run
bundle install and
foreman start. Navigate to localhost:9292. Register using the Slack button.
If you deploy to Heroku set
heroku config:add SLACK_CLIENT_ID=... SLACK_CLIENT_SECRET=....
This library implements an app, SlackRubyBotServer::App, a service manager, SlackRubyBotServer::Service that creates multiple instances of a bot server class, SlackRubyBotServer::Server, one per team.
The app instance checks for a working MongoDB connection, ensures database indexes, performs database migrations, sets up bot aliases and log levels. You can introduce custom behavior into the app lifecycle by subclassing
SlackRubyBotServer::App and creating an instance of the child class in
class MyApp < SlackRubyBotServer::App def prepare! super deactivate_sleepy_teams! end private def deactivate_sleepy_teams! Team.active.each do |team| next unless team.sleepy? team.deactivate! end end end
You can introduce custom behavior into the service lifecycle via callbacks. This can be useful when new team has been registered via the API or a team has been deactivated from Slack.
instance = SlackRubyBotServer::Service.instance instance.on :created do |team, error| # a new team has been registered end instance.on :deactivated do |team, error| # an existing team has been deactivated in Slack end instance.on :error do |team, error| # an error has occurred end
The following callbacks are supported. All callbacks receive a
error, which receives a
|error||an error has occurred|
|creating||a new team is being registered|
|created||a new team has been registered|
|booting||the service is starting and is connecting a team to Slack|
|booted||the service is starting and has connected a team to Slack|
|stopping||the service is about to disconnect a team from Slack|
|stopped||the service has disconnected a team from Slack|
|starting||the service is (re)connecting a team to Slack|
|started||the service has (re)connected a team to Slack|
|deactivating||a team is being deactivated|
|deactivated||a team has been deactivated|
You can override the server class to handle additional events, and configure the service to use it.
class MyServer < SlackRubyBotServer::Server on :hello do |client, data| # connected to Slack end on :channel_joined do |client, data| # the bot joined a channel in data.channel['id'] end end SlackRubyBotServer.configure do |config| config.server_class = MyServer end
By default the implementation of Team stores a
bot_access_token that grants a certain amount of privileges to the bot user as described in Slack OAuth Docs. You may not want a bot user at all, or may require different auth scopes, such as
users.profile:read to access user profile information via
Slack::Web::Client#users_profile_get. To obtain the non-bot access token make the following changes.
- Configure your app to require additional scopes in Slack API under OAuth, Permissions
- Change the Add to Slack buttons to require the additional scope, eg.
- Store the access token returned from
Slack::Web::Client#oauth_accessand scope when creating a team in your
You can see a sample implementation in slack-sup#3a497b.
Examples Using Slack Ruby Bot Server
- slack-amber-alert, free service at missingkidsbot.org
- slack-sup, free service at sup.playplay.io
- slack-gamebot, free service at www.playplay.io
- slack-market, free service at market.playplay.io
- slack-shellbot, free service at shell.playplay.io
- slack-api-explorer, free service at api-explorer.playplay.io
Copyright & License
Copyright Daniel Doubrovkine and Contributors, 2015-2017