Slack Bot Manager

Slack Bot Manager is a Ruby gem that allows for the management of multiple Slack RTM connections based on tokens. With only a few configuration changes, you can run a system for handling hundreds of simulatenous RTM connections for your Slack app.

This is in pre-release and may change before release of version 0.1.0.

How to tell if you need this:

• You are making a Slack app requiring Real-time Messaging
• You want to be able to handle multiple RTM connections
• You don't want to make your own RTM (websocket) connection manager

Installation

gem 'slack-bot-manager'

This gem requires a key-value storage system for managing tokens and connection statuses. Currently, this gem supports redis and dalli (memcached).

gem 'redis'
gem 'dalli'

Getting Started

To get started, get a token (or few) and start your script.

botmanager = SlackBotManager::Manager.new
botmanager.add_token('token1', 'token2', 'token3')
botmanager.start
botmanager.monitor

Running the Slack Bot Manager

Once you initialize a new SlackBotManager::Manager, you can use the following connection and token methods to run your cool new Slack bot app.

Manager Connection Methods

You can run a manager supporting multiple RTM connections with just three lines!

botmanager = SlackBotManager::Manager.new
botmanager.start
botmanager.monitor

These are the available connecton methods:

methods	description
start	Start connections by fetching known tokens and creating each connection
stop	Stop connections
restart	Restart connections
status	Get the status of the current manager (number of connections).
monitor	Run the manager in a continuous loop, checking for changes in connections and token statuses.

Token Management Methods

Tokens are managed using the defined storage adapter (Redis or Dalli). SlackBotManager will manage and monitor these keys for additions, updates, and removals. New connections will be added into the key teams_key, like so:

botmanager = SlackBotManager::Manager.new
botmanager.add_token('token1', 'token2', 'token3') # takes array

These are the available token methods:

methods	description
add_token(*tokens)	Add new token(s), will connect within monitor loop. [array]
remove_token(*tokens)	Remove token(s), will disconnect within monitor loop. [array]
update_token(*tokens)	Update token(s), will trigger update methods within monitor loop. [array]
check_token(*tokens)	Check the status of token(s), output status(es). [array]

Client Connections

Each RTM connection handled by SlackBotManager::Manager is generated by SlackBotManager::Client. This client class assists in checking RTM (websocket) connection status, storing various attributes, and includes event listener support.

The following instance variables are accessible by Client and the included Commands module:

variable	description
connection	Slack::RealTime::Client connection
id	Team's Slack ID (ex. T123ABC) (set after successful connection)
token	Team's Slack access token (ex. xoxb-123abc456def)
status	Known connection status. (connected, disconnected, rate_limited, token_revoked)
storage	Storage adapter from Config.

Client Methods

These are some common client methods you can use to manage incoming events and interact with Slack.

methods	description
message(channel, text, {})	Send a message to channel. Handles both simple RTM message or chat.postMessage if additional options are present.
typing(channel, {})	Send typing notification.
ping({})	Send a manual ping to Slack.
on(event, &block)	Add an event listener. (Same as extending with on_* methods.)
off(event, &block)	Remove an event listener. (Does not remove defined on_* methods.)

Adding Event Listeners

You will want to handle your own RTM event listeners to perform specific functions. This is achieved by extending the SlackBotManager:Commands module, which is included within the SlackBotManager::Client class (and access to subsequent instance variables specific to that connection).

Each event must be prefixed with on_, e.g. on_messsage will handing incoming messages.

module SlackBotManager
  module Commands
    def on_hello(data)
      puts "Connected to %s" % self.id
    end

    def on_team_join(data)
      message(data['channel'], "Welcome: %s" % data['user']['username'])
    end
  end
end

(A full list of events is available from the Slack API docs.)

Configuration

Global configuration options

setting	description
storage_adapter	Token storage method. (default: nil)
storage_options	Token storage method options. (default: {})
logger	Define the logger to use. (default: Rails.logger or ::Logger.new(STDOUT))
log_level	Explicity define the logger level. (default: ::Logger::WARN)
verbose	When true, set log_level to ::Logger::DEBUG. (default: false)

You can define these configuration options as:

SlackBotManager.configure do |config|
  config.storage_adapter = SlackBotManager::Storage::Redis
  config.storage_options = {host: '0.0.0.0', port: 6379}
end

Manager configuration options

Manager configuration options include the global options (storage_adapter, storage_options, logger, log_level, & verbose), in addition to:

setting	description
tokens_key	Redis key name for where tokens' status are stored. (default: tokens:statuses)
teams_key	Redis key name for where teams' tokens are stored. (default: tokens:teams)
check_interval	Interval (in seconds) for checking connections and tokens status. (default: 5)

You can define these configuration options as:

SlackBotManager::Manager.configure do |config|
  config.storage_adapter = SlackBotManager::Storage::Redis
  config.storage_options = {host: '0.0.0.0', port: 6379}
  config.check_interval = 10 # in seconds
end

You can additionally send an existing storage method as the storage_option, such as:

$redis = Redis.new
SlackBotManager::Manager.configure do |config|
  config.storage_options = $redis
end

Client configuration options

Client configuration options include the global options (storage_adapter, storage_options, logger, log_level, & verbose)

You can define these configuration options as:

SlackBotManager::Client.configure do |config|
  config.log_level = ::Logger::INFO
end

Additional configuration options

For customization of Slack connections, including proxy, websocket ping, endpoint, user-agent, and more, check out the slack-ruby-client README.

Examples

You can check a few creative examples in the examples folder.

History

This gem will be released soon, and is based on earlier work created by betaworks for PlusPlus++ Slack app.

Also thanks to slack-ruby-client.

Contributing

See CONTRIBUTING.

Thanks to our contributors Greg Leuch and Alex Baldwin.

Copyright and License

Copyright (c) 2016 Greg Leuch & betaworks.

Licensed under MIT License.