A library that enables you to write a complete Slack bot service with Slack button integration, in Ruby.
Ruby JavaScript HTML
Clone or download
dblock Merge pull request #72 from dblock/upgrade-rubocop
Upgrade rubocop to 0.55.0.
Latest commit 9458a50 May 7, 2018
Permalink
Failed to load latest commit information.
images Recorded a new version of slack button and update README. [ci skip] Jan 11, 2016
lib Upgrade rubocop to 0.55.0. May 7, 2018
public Repo moved to the slack-ruby organization. Aug 29, 2016
sample_apps Upgrade rubocop to 0.55.0. May 7, 2018
script Renamed slack-bot-server to slack-ruby-bot-server. Jun 1, 2016
spec Upgrade rubocop to 0.55.0. May 7, 2018
tasks Relaxed dependency versions, notably enabling grape 0.16.2 and Swagge… Jun 20, 2016
.gitignore Added Rake tasks for gem release, reset version to 0.1.0. Jun 1, 2016
.rspec Slack bot server with a Grape API skeleton. Nov 10, 2015
.rubocop.yml Upgrade rubocop to 0.55.0. May 7, 2018
.rubocop_todo.yml Upgrade rubocop to 0.55.0. May 7, 2018
.travis.yml Updated Capybara and Selenium-Webdriver. Aug 16, 2017
CHANGELOG.md Don't try to load OTR module is Rails (#67) Aug 29, 2017
CONTRIBUTING.md Repo moved to the slack-ruby organization. Aug 29, 2016
DEBUGGING.md Renamed slack-bot-server to slack-ruby-bot-server. Jun 1, 2016
Dangerfile Use slack-ruby-danger gem. (#28) Sep 5, 2016
Gemfile Upgrade rubocop to 0.55.0. May 7, 2018
Guardfile Slack bot server with a Grape API skeleton. Nov 10, 2015
LICENSE Added slack-sup sample. [ci skip] Aug 30, 2017
README.md Added slack-sup sample. [ci skip] Aug 30, 2017
RELEASING.md Preparing for next development iteration, 0.6.1. Mar 12, 2017
Rakefile Upgrade rubocop to 0.55.0. May 7, 2018
UPGRADING.md Fix: starting sample apps. Mar 7, 2017
app.json Repo moved to the slack-ruby organization. Aug 29, 2016
slack-ruby-bot-server.gemspec Upgrade rubocop to 0.55.0. May 7, 2018

README.md

Slack Ruby Bot Server

Gem Version Build Status Code Climate

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.

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, v0.6.1 unless you're integrating with HEAD. See UPGRADING when upgrading from an older version.

Try Me

A demo version of the sample app with mongoid is running on Heroku at slack-ruby-bot-server.herokuapp.com. Use the Add to Slack button. The bot will join your team as @slackbotserver.

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.

MongoDB

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.

ActiveRecord

Use ActiveRecord with, for example, PostgreSQL via pg. Configure the database connection in postgresql.yml. 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'

See the sample app using ActiveRecord for more information.

Usage

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_ID=... and 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 SLACK_CLIENT_ID and SLACK_CLIENT_SECRET via heroku config:add SLACK_CLIENT_ID=... SLACK_CLIENT_SECRET=....

API

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.

App

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 config.ru.

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
MyApp.instance.prepare!

Service Manager

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

Server Class

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

Access Tokens

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.

  1. Configure your app to require additional scopes in Slack API under OAuth, Permissions
  2. Add access_token and, optionally, scope to your Team model
  3. Change the Add to Slack buttons to require the additional scope, eg. https://slack.com/oauth/authorize?scope=bot,users.profile:read&client_id=...
  4. Store the access token returned from Slack::Web::Client#oauth_access and scope when creating a team in your Teams API endpoint.

You can see a sample implementation in slack-sup#3a497b.

Examples Using Slack Ruby Bot Server

Copyright & License

Copyright Daniel Doubrovkine and Contributors, 2015-2017

MIT License