Skip to content


Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

Slack Ruby Bot Server

Gem Version Code Climate mongodb postgresql rubocop

Build a complete Slack bot service with Slack button integration, in Ruby.

Table of Contents

What is this?

A library that contains a web server and a RESTful Grape API serving a Slack bot to multiple teams. Use in conjunction with slack-ruby-bot-server-events to build a complete Slack bot service, or slack-ruby-bot-server-rtm to build a (legacy) Classic RealTime Slack bot. Your customers can use a Slack button to install the bot.

Stable Release

You're reading the documentation for the next release of slack-ruby-bot-server. Please see the documentation for the last stable release, v1.2.1 unless you're integrating with HEAD. See UPGRADING when upgrading from an older version. See MIGRATING for help with migrating Legacy Slack Apps to Granular Scopes.

Make Your Own

This library alone will only register a new bot, but will not include any bot functionality. To make something useful, we recommend you get started from either slack-ruby-bot-server-events-app-mentions-sample (handles a single kind of event), or slack-ruby-bot-server-events-sample (handles all kinds of events) to bootstrap your project.



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'


Use ActiveRecord with, for example, PostgreSQL via pg. Add the activerecord, pg, otr-activerecord and cursor_pagination gems to your Gemfile.

gem 'pg'
gem 'activerecord', require: 'active_record'
gem 'slack-ruby-bot-server'
gem 'otr-activerecord'
gem 'cursor_pagination'

Configure the database connection in config/postgresql.yml.

default: &default
  adapter: postgresql
  pool: 10
  timeout: 5000
  encoding: unicode

  <<: *default
  database: bot_development

  <<: *default
  database: bot_test

  <<: *default
  database: bot

Establish a connection in your startup code.

    ).result, [], [], true

OAuth Version and Scopes

Configure your app's OAuth version and scopes as needed by your application.

SlackRubyBotServer.configure do |config|
  config.oauth_version = :v2
  config.oauth_scope = ['channels:read', 'chat:write']

The "Add to Slack" button uses the standard OAuth code grant flow as described in the Slack docs. Once clicked, the user is taken through the authorization process at Slack's site. Upon successful completion, a callback containing a temporary code is sent to the redirect URL you specified. The endpoint at that URL contains code that persists the bot token each time a Slack client is instantiated for the specific team.

Slack App

Create a new Slack App here.

Follow Slack's instructions, note the app client ID and secret, give the bot a default name, etc.

Within your application, edit your .env file and add SLACK_CLIENT_ID=... and SLACK_CLIENT_SECRET=... in it.

Run bundle install and foreman start to boot the app.

$ foreman start
07:44:47 web.1  | started with pid 59258
07:44:50 web.1  | * Listening on tcp://

Set the redirect URL in "OAuth & Permissions" be the location of your app. Since you cannot receive notifications on localhost from Slack use a public tunneling service such as ngrok to expose local port 9292 for testing.

$ ngrok http 5000
Forwarding -> http://localhost:5000

Navigate to either localhost:9292 or the ngrok URL above. You should see an "Add to Slack" button. Use it to install the app into your own Slack team.


This library implements an app, SlackRubyBotServer::App and a service manager, SlackRubyBotServer::Service. It also provides default HTML templates and JS scripts for Slack integration.


The app instance checks for a working database connection, ensures indexes, performs 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!


  def deactivate_sleepy_teams! do |team|
      next unless team.sleepy?

Service Manager

Lifecycle Callbacks

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 :started, :stopped do |team|
  # team has been started or stopped

instance.on :created do |team, error, options|
  # a new team has been registered

instance.on :deactivated do |team, error, options|
  # an existing team has been deactivated in Slack

instance.on :error do |team, error, options|
  # an error has occurred

The following callbacks are supported. All callbacks receive a team, except error, which receives a StandardError object.

callback description
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

The Add to Slack button also allows for an optional state parameter that will be returned on completion of the request. The creating and created callbacks include an options hash where this value can be accessed (to check for forgery attacks for instance).

auth = OpenSSL::HMAC.hexdigest("SHA256", "key", "data")
<a href="<%= SlackRubyBotServer::Config.oauth_authorize_url %>?scope=<%= SlackRubyBotServer::Config.oauth_scope_s %>&client_id=<%= ENV['SLACK_CLIENT_ID'] %>&state=#{auth)"> ... </a>
instance = SlackRubyBotServer::Service.instance
instance.on :creating do |team, error, options|
  raise "Unauthorized response" unless options[:state] == auth
Service Timers

You can introduce custom behavior into the service lifecycle on a timer. For example, check whether a team's trial has expired, or periodically cleanup data.

Note that unlike callbacks, timers are global for the entire service.

instance = SlackRubyBotServer::Service.instance

instance.every :hour do
  Team.each do |team|
      # do something with every team once an hour
    rescue StandardError

instance.every :minute do
  # called every minute

instance.every :second do
  # called every second

instance.every 30 do
  # called every 30 seconds

A number of extensions use service manager callbacks and service timers to implement useful functionality.

Service Class

You can override the service class to handle additional methods.

class MyService < SlackRubyBotServer::Service
  def url

SlackRubyBotServer.configure do |config|
  config.service_class = MyService

SlackRubyBotServer::Service.instance # MyService
SlackRubyBotServer::Service.instance.url #

HTML Templates

This library provides a default HTML template and JS scripts that implement the "Add to Slack" button workflow. Customize your pages by adding a public directory in your application and starting with a index.html.erb template. The application's views and public folders are loaded by default.

You can add to or override template paths as follows.

SlackRubyBotServer.configure do |config|
  config.view_paths << File.expand_path(File.join(__dir__, 'public'))

Access Tokens

By default the implementation of Team stores the value of the token with all the requested OAuth scopes in both token and activated_user_access_token (for backwards compatibility), along with oauth_version and oauth_scope. If a legacy Slack bot integration bot_access_token is present, it is stored as token, and activated_user_access_token is the token that has all the requested OAuth scopes.

Sample Bots Using Slack Ruby Bot Server

Slack Bots with Granular Permissions

Legacy Slack Bots

Copyright & License

Copyright Daniel Doubrovkine and Contributors, 2015-2020

MIT License


A library that enables you to write a complete Slack bot service with Slack button integration, in Ruby.







Sponsor this project



No packages published