Slack Ruby Bot Server

Slack Ruby Bot Server is a Ruby library that provides a web server and a RESTful Grape API designed to serve a Slack bot to multiple teams. It enables customers to install the bot via Slack buttons.

To build a complete, functional Slack bot service, this library should be used in conjunction with slack-ruby-bot-server-events.

When upgrading to version 1.2.0 or higher, new fields oauth_scope and oauth_version were added to the Team model. If you are using ActiveRecord, you must create a migration to add these columns. No action is required for Mongoid users.

class AddOauthFields < ActiveRecord::Migration[5.0]
  def change
    add_column :teams, :oauth_scope, :string
    add_column :teams, :oauth_version, :string, default: 'v1', null: false
  end
end

The slack-ruby-bot-server library handles the registration of a new bot but does not include built-in bot logic/functionality. To implement actual bot behavior, you should bootstrap your project using one of the following sample repositories:

1. slack-ruby-bot-server-events-app-mentions-sample: Recommended if you want to handle a single specific kind of event (e.g., app mentions).
2. slack-ruby-bot-server-events-sample: Recommended if you want to handle all kinds of events.

Starting from version 0.6.0, the mongoid gem is no longer a hard dependency. You must manually add either mongoid or activerecord (along with its driver) to your Gemfile. The order of declaration is important: the driver must be required before activerecord to avoid errors.

# For Mongoid
gem 'mongoid'
gem 'slack-ruby-bot-server'

# For ActiveRecord (with PostgreSQL)
gem 'pg'
gem 'activerecord', require: 'active_record'
gem 'slack-ruby-bot-server'

Slack now requires new apps to use granular permissions. To migrate, you must replace the real-time implementation (slack-ruby-bot-server-rtm) with the events-based implementation (slack-ruby-bot-server-events).

Because existing installations cannot be automatically migrated, users must reinstall the bot. This migration strategy allows you to run both the old (RTM) and new (Events) versions simultaneously using the same database. The slack-ruby-bot-server (v1.2.0+) tracks oauth_version and oauth_scope on the Team model, allowing the RTM server to ignore newer granular-permission installs and the Events server to ignore legacy RTM installs.

To use MongoDB as your storage backend, add the mongoid gem along with kaminari-mongoid and mongoid-scroll to your Gemfile. You must configure your database connection in a mongoid.yml file.

gem 'mongoid'
gem 'kaminari-mongoid'
gem 'mongoid-scroll'
gem 'slack-ruby-bot-server'

As of version 1.1.0, RTM (RealTime Messaging) components are no longer included in the core slack-ruby-bot-server gem. To upgrade an existing classic Slack app that requires RTM, follow these steps:

1. Add slack-ruby-bot-server-rtm as a dependency in your Gemfile.
2. Replace all references to SlackRubyBotServer::Server with SlackRubyBotServer::RealTime::Server.
3. Replace require 'slack-ruby-bot-server/rspec' with require 'slack-ruby-bot-server-rtm/rspec'.
4. Configure the bot to use Slack OAuth 1.0 and specify the required scopes.

SlackRubyBotServer.configure do |config|
  config.oauth_version = :v1
  config.oauth_scope = ['bot']
end

When upgrading to version 0.10.0 or higher, new fields were added to the Team model: bot_user_id, activated_user_id, and activated_user_access_token. If you are using ActiveRecord, you must create a migration to add these fields. No action is required for Mongoid users.

class AddActivatedFields < ActiveRecord::Migration[5.0]
  def change
    add_column :teams, :bot_user_id, :string
    add_column :teams, :activated_user_id, :string
    add_column :teams, :activated_user_access_token, :string
  end
end

1. Create a Slack App at api.slack.com.
2. Add SLACK_CLIENT_ID and SLACK_CLIENT_SECRET to your .env file.
3. Set your Redirect URL in the Slack App settings under 'OAuth & Permissions'.
4. For local testing, use a tool like ngrok to expose your local port (e.g., 5000) to a public URL, and use that public URL as the Redirect URL in Slack.
5. Run the app using foreman start.

$ foreman start
$ ngrok http 5000

When upgrading to version 2.0.0 or higher, the abandoned cursor_pagination gem is replaced by pagy_cursor. If you are using ActiveRecord, you must update your Gemfile to use pagy_cursor instead.

gem 'pagy_cursor'

To migrate without downtime, deploy the new granular-permission app alongside the old RTM app using the same production database.

1. New App Setup: Create a new Slack App with granular permissions. Use its SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, and SLACK_SIGNING_SECRET for the new deployment.
2. Shared Database: Ensure both the legacy RTM bot and the new Events bot point to the same database instance.
3. DNS/Event URLs: Once deployed, update your DNS and ensure Slack Event URLs are correctly configured to point to the new service.
4. Team Migration: Existing teams can be migrated by having them uninstall the old bot and reinstall the new one. The data remains intact in the shared database.