Skip to content

betaworks/slack-bot-manager

Repository files navigation

Slack Bot Manager

Gem Version Build Status Code Climate

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.

About

Slack RealTime API client connection manager Ruby gem

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages