There's a lot of open issues
A long-lived project that still receives updates
Slack Web and RealTime API client.
 Project Readme

Slack Ruby Client

Gem Version Integration Tests Tests Code Climate

A Ruby client for the Slack Web, RealTime Messaging and Events APIs. Comes with a handy command-line client, too. If you are not familiar with these concepts, you might want to watch this video.

Table of Contents

  • Useful to Me?
  • Stable Release
  • Installation
  • Usage
    • Create a New Bot Integration
    • OAuth Code Grant
    • Using an API Token
    • Global Settings
    • Web Client
      • Web Client Examples
        • Test Auth
        • Send Messages
        • List Channels
        • Upload a File
        • Get Channel Info
        • Get User Info
        • Search for a User
        • Other
      • JSON Arguments
      • Web Client Options
      • Pagination Support
      • Character Encoding
      • Error Handling
        • Slack Errors
        • Rate Limiting
        • Other Errors
    • RealTime Client
      • Configuring Slack::RealTime::Client
        • Caveats
          • websocket_ping
      • RealTime Store
        • Slack::RealTime::Stores::Starter
        • Slack::RealTime::Stores::Store
    • Combining RealTime and Web Clients
      • Concurrency
        • Async
    • Events API
      • Configuring Slack::Events
      • Verifying the Request Signature
    • Message Parsing
    • Command-Line Client
      • Authenticate with Slack
      • Send a Message
      • Get Channel Info
      • List Users
  • Enterprise Support
  • History
  • Security
  • Contributing
  • Copyright and License

Useful to Me?

  • This library will let you send messages to Slack via the Web API, send and receive messages via the Real Time Messaging API and facilitate integration with the Events API.
  • To respond to slash commands, interactive components or events, implement a web application using your favorite web framework and use this library to call the Slack Web API and to verify that events are coming from Slack.
  • To build a bot using the Real Time Messaging API, use slack-ruby-bot, which uses this library.
  • To roll out a complete service using the Real Time Messaging API with Slack button integration to multiple teams, check out slack-ruby-bot-server, which is built on top of slack-ruby-bot, which uses this library.

Stable Release

You're reading the documentation for the next release of slack-ruby-client. Please see the documentation for the last stable release, v2.1.0 unless you're integrating with HEAD. See UPGRADING when upgrading from an older version.


Add to Gemfile.

gem 'slack-ruby-client'

If you're going to be using the RealTime client, add async-websocket. See below for more information about concurrency.

gem 'async-websocket', '~> 0.8.0'

Run bundle install.


Create a New Bot Integration

To integrate your bot with Slack, you must first create a new Slack App.

OAuth Code Grant

Once created, go to the app's Basic Info tab and grab the Client ID and Client Secret. You'll need these in order complete an OAuth code grant flow as described at slack-ruby-bot-server.

Using an API Token

Although OAuth is recommended, you can also generate an API token for your app and use it for some interactions.

Slack.configure do |config|
  config.token = ENV['SLACK_API_TOKEN']

This sets a global default token. You can also pass a token into the initializer of both Slack::Web::Client and Slack::RealTime::Client or configure those separately via Slack::Web::Config.configure and Slack::RealTime::Config.configure. The instance token will be used over the client type token over the global default.

Global Settings

The following global settings are supported via Slack.configure.

setting description
token Slack API token.
logger An optional logger, defaults to at Logger::WARN level.

Web Client

The Slack Web API allows you to build applications that interact with Slack.

Web Client Examples

Here are some examples of how to use the web client with the Web API.

Test Auth
client =
Send Messages

Send messages with chat_PostMessage.

client.chat_postMessage(channel: '#general', text: 'Hello World', as_user: true)

See a fully working example in examples/hi_web.

List Channels

List channels with conversations_list.

channels = client.conversations_list.channels

general_channel = channels.detect { |c| == 'general' }
Upload a File

Upload a file with files_upload.

  channels: '#general',
  as_user: true,
  file:'/path/to/avatar.jpg', 'image/jpeg'),
  title: 'My Avatar',
  filename: 'avatar.jpg',
  initial_comment: 'Attached a selfie.'
Get Channel Info

You can use a channel ID or name (prefixed with #) in all functions that take a :channel argument. Lookup by name is not supported by the Slack API and the channels_id method called invokes conversations_list in order to locate the channel ID. This invocation can have a cost if you have many Slack channels. In this scenario, we encourage you to use channel id.

client.conversations_info(channel: 'C04KB5X4D') # calls conversations_info
client.conversations_info(channel: '#general') # calls conversations_list followed by conversations_info
Get User Info

You can use a user ID or name (prefixed with @) in all functions that take a :user argument. Lookup by name is not supported by the Slack API and the users_id method called invokes users_list in order to locate the user ID.

client.users_info(user: 'U092BDCLV') # calls users_info
client.users_info(user: '@dblock') # calls users_list followed by users_info
Search for a User

Constructs an in-memory index of users and searches it. If you want to use this functionality, add the picky gem to your project's Gemfile.

client.users_search(user: 'dblock')

Refer to the Slack Web API Method Reference for the list of all available functions.

JSON Arguments

The Web API expects certain arguments to be sent as JSON-encoded strings. With the client you can pass these args as ruby hashes or arrays and they will be converted automatically to JSON, or you can provide the JSON directly.

# As ruby objects
  channel: 'C123456',
  text: 'Hello World',
  blocks: [{type: 'section', text: {type: 'mrkdwn', text: 'Hello World'}}]

# As a JSON string
  channel: 'C123456',
  text: 'Hello World',
  blocks: JSON.dump([{type: 'section', text: {type: 'mrkdwn', text: 'Hello World'}}])
  channel: 'C123456',
  text: 'Hello World',
  blocks: '[{"type":"section","text":{"type":"mrkdwn","text":"Hello World"}}]'

Web Client Options

You can configure the Web client either globally or via the initializer.

Slack::Web::Client.configure do |config|
  config.user_agent = 'Slack Ruby Client/1.0'
client = 'Slack Ruby Client/1.0')

The following settings are supported.

setting description
token Slack API token.
user_agent User-agent, defaults to Slack Ruby Client/version.
proxy Optional HTTP proxy.
ca_path Optional SSL certificates path.
ca_file Optional SSL certificates file.
endpoint Slack endpoint, default is
logger Optional Logger instance that logs HTTP requests.
timeout Optional open/read timeout in seconds.
open_timeout Optional connection open timeout in seconds.
default_page_size Optional page size for paginated requests, default is 100.
default_max_retries Optional number of retries for paginated requests, default is 100.
adapter Optional HTTP adapter to use, defaults to Faraday.default_adapter.

You can also pass request options, including timeout and open_timeout into individual calls.

client.conversations_list(request: { timeout: 180 })

You can also control what proxy options are used by modifying the http_proxy environment variable per Net::HTTP's documentation.

Note that Docker on OSX seems to incorrectly set the proxy, causing Faraday::ConnectionFailed, ERROR -- : Failed to open TCP connection to : (getaddrinfo: Name or service not known). You might need to manually unset http_proxy in that case, eg. http_proxy="" bundle exec ruby ./my_bot.rb.

Pagination Support

The Web client natively supports cursor pagination for methods that allow it, such as users_list. Supply a block and the client will make repeated requests adjusting the value of cursor with every response. The default limit is set to 100 and can be adjusted via Slack::Web::Client.config.default_page_size or by passing it directly into the API call.

all_members = []
client.users_list(presence: true, limit: 10) do |response|
all_members # many thousands of team members retrieved 10 at a time

When using cursor pagination the client will automatically pause and then retry the request if it runs into Slack rate limiting. (It will pause according to the Retry-After header in the 429 response before retrying the request.) If it receives too many rate-limited responses in a row it will give up and raise an error. The default number of retries is 100 and can be adjusted via Slack::Web::Client.config.default_max_retries or by passing it directly into the method as max_retries.

You can also proactively avoid rate limiting by adding a pause between every paginated request with the sleep_interval parameter, which is given in seconds.

all_members = []
client.users_list(presence: true, limit: 10, sleep_interval: 5, max_retries: 20) do |response|
  # pauses for 5 seconds between each request
  # gives up after 20 consecutive rate-limited responses
all_members # many thousands of team members retrieved 10 at a time

Character Encoding

Note that Slack expects text to be UTF-8 encoded. If your messages appear with text such as BAD+11 in Slack, check text.encoding and .encode(Encoding::UTF_8) your messages before sending them to Slack.

text = 'characters such as "Ñ", "Á", "É"'
=> #<Encoding:UTF-8>
client.chat_postMessage(channel: '#general', text: text, as_user: true)
# renders 'characters such as "Ñ", "Á", "É"' in Slack

text = text.encode(Encoding::ISO_8859_1)
# => #<Encoding:ISO-8859-1>
client.chat_postMessage(channel: '#general', text: text, as_user: true)
# renders 'characters such as "BAD+11", "", "BAD+9"' in Slack

Error Handling

Slack Errors

If Slack returns an error for the request, then an error will be raised. The error class is specific to the type of error that Slack returns. For instance if Slack returns account_inactive then the error will be Slack::Web::Api::Errors::AccountInactive. This allows you to handle certain types of errors as needed:

rescue Slack::Web::Api::Errors::AccountInactive => e
  # deal with inactive account

All of these errors inherit from Slack::Web::Api::Errors::SlackError, so you can handle or silence all errors if necessary:

rescue Slack::Web::Api::Errors::SlackError => e
  # capture all Slack errors

If there's a new error type that is not yet known by this library, then it will raise Slack::Web::Api::Errors::SlackError. (Update the Web API if you find that errors are missing — see CONTRIBUTING.)

In all of these cases the error message contains the error code, which is also accessible with slack_error.error. In case of multiple errors, the error message contains the error codes separated by commas, or they are accessible as an array with slack_error.errors. The original response is also accessible using the response attribute. The response_metadata is accessible with slack_error.response_metadata.

Rate Limiting

If you exceed Slack’s rate limits, a Slack::Web::Api::Errors::TooManyRequestsError will be raised instead. (This does not inherit from Slack::Web::Api::Errors::SlackError.)

Other Errors

When Slack is temporarily unavailable a subclass of Slack::Web::Api::Errors::ServerError will be raised and the original Faraday::Error will be accesible via exception.cause. (Starting with 0.18.0 this is no longer a subclass of Slack::Web::Api::Errors::SlackError.)

Specifically Slack::Web::Api::Errors::ParsingError will be raised on non-json response (i.e. 200 OK with Slack unavailable HTML page) and Slack::Web::Api::Errors::HttpRequestError subclasses for connection failures (Slack::Web::Api::Errors::TimeoutError for read/open timeouts & Slack::Web::Api::Errors::UnavailableError for 5xx HTTP responses).

In any other case, a Faraday::ClientError will be raised.

RealTime Client

The Real Time Messaging API is a WebSocket-based API that allows you to receive events from Slack in real time and send messages as user.

client =

client.on :hello do
  puts "Successfully connected, welcome '#{}' to the '#{}' team at https://#{}"

client.on :message do |data|
  case data.text
  when 'bot hi' then
    client.message(channel:, text: "Hi <@#{data.user}>!")
  when /^bot/ then
    client.message(channel:, text: "Sorry <@#{data.user}>, what?")

client.on :close do |_data|
  puts "Client is about to disconnect"

client.on :closed do |_data|
  puts "Client has disconnected successfully!"


You can send typing indicators with typing.

client.typing channel:

You can send a ping with ping.

Configuring Slack::RealTime::Client

You can configure the RealTime client either globally or via the initializer.

Slack::RealTime::Client.configure do |config|
  config.websocket_ping = 42
client = 42)

The following settings are supported.

setting description
token Slack API token.
websocket_ping How long the socket can be idle before sending a ping message to confirm it's still connected, default is 30.
websocket_proxy Connect via proxy, include :origin and :headers.
start_options Options to pass to rtm.connect, default is { request: { timeout: 180 } }.
store_class Local store class, default is an in-memory Slack::RealTime::Stores::Starter.
store_options Options to initialize the store, default is {}.
logger Optional Logger instance that logs RealTime requests and socket data.

Note that the RealTime client uses a Web client to obtain the WebSocket URL via rtm.connect. While token and logger options are passed down from the RealTime client, you may also configure Web client options via Slack::Web::Client.configure as described above.

See a fully working example in examples/hi_real_time_and_web.


This setting determines how long the socket can be idle before sending a ping message to confirm it's still connected.

It's important to note that if a ping message was sent and no response was received within the amount of time specified in websocket_ping the client will attempt to reestablish it's connection to the message server.

Note that the ping may take between websocket_ping and websocket_ping * 3/2 seconds to actually trigger when there is no activity on the socket. This is because the timer that checks whether to ping is triggered at every websocket_ping / 2 interval.

To disable this feature set websocket_ping to 0.

RealTime Store

The RealTime client exposes and maintains a local store upon successful connection. Event hooks keep the store's cached data up-to-date.

Tracking with a local store can be disabled with nil).


A small store that only caches and tracks data returned in the rtm.connect response. This store provides self and team for accessing the limited data about the authenticated user and its workspace, but does not cache other users or bots, channels, or direct messages.


A more complete store that tracks most changes visible to the authenticated user.

You can see all of the cache types in the table below (each is a hash indexed by its objects' id).

Cache Description
teams Workspaces (teams). Will likely contain only one team.
users All user objects, including self.
bots All bot users (from Slack Apps and legacy custom integrations).
public_channels Public conversation objects.
private_channels Private conversation and group objects with the authenticated user as a member.
ims Visible im objects, direct message channels with the authenticated user.
mpims Visible mpim objects, multiparty direct message channels that include the authenticated user.

By default, none of these caches are initialized with data beyond what is returned from rtm.connect, same as Slack::RealTime::Stores::Starter. When configured, this store initializes its caches by making additional calls to Web API methods upon successful connection to the RTM API (i.e. "hello" message).

Configure by specifying which caches to fetch:

Slack::RealTime::Client.configure do |config|
  config.store_class = Slack::RealTime::Stores::Store
  config.store_options = { caches: %i[teams users public_channels private_channels ims] }

or with the :all option:

Slack::RealTime::Client.configure do |config|
  config.store_class = Slack::RealTime::Stores::Store
  config.store_options = { caches: :all }

Note: For teams, this makes a single call to, while for users and all conversation-like types, this makes paginated calls to users.list and conversations.list respectively. Only bots requires a separate call for every bot user, so may be slow if your workplace has a lot of bot users.

Combining RealTime and Web Clients

Since the Web client is used to obtain the RealTime client's WebSocket URL, you can continue using the Web client in combination with the RealTime client.

client =

client.on :message do |data|
  case data.text
  when 'bot hi' then
    client.web_client.chat_postMessage(channel:, text: "Hi <@#{data.user}>!")
  when /^bot/ then
    client.web_client.chat_postMessage(channel:, text: "Sorry <@#{data.user}>, what?")


See a fully working example in examples/hi_real_time_and_web.


Slack::RealTime::Client needs help from a concurrency library and supports Async.

Slack::RealTime.configure do |config|
  config.concurrency = Slack::RealTime::Concurrency::Async

Use client.start_async instead of client.start!. A good example of such application is slack-ruby-bot-server.

client =


Add async-websocket to your Gemfile.

gem 'async-websocket'

See a fully working example in examples/hi_real_time_async_async.

Events API

This library provides limited support for the Slack Events API.

Configuring Slack::Events

You can configure Events support globally.

Slack::Events.configure do |config|
  config.signing_secret = 'secret'

The following settings are supported.

setting description
signing_secret Slack signing secret, defaults is ENV['SLACK_SIGNING_SECRET'].
signature_expires_in Signature expiration window in seconds, default is 300.

Verifying the Request Signature

Slack signs its requests using a secret that's unique to your app. Verify incoming HTTP requests as follows.

slack_request =

To specify secrets on a per-request basis:,
                           signing_secret: signing_secret,
                           signature_expires_in: signature_expires_in)

The verify! call may raise Slack::Events::Request::MissingSigningSecret, Slack::Events::Request::InvalidSignature or Slack::Events::Request::TimestampExpired errors.

Message Parsing

All text in Slack uses the same system of escaping: chat messages, direct messages, file comments, etc. Use Slack::Messages::Formatting to escape or unescape messages. This comes handy, for example, you want to treat all input to a real time bot as plain text.

Slack::Messages::Formatting.unescape('Hello &amp; &lt;world&gt;'))
  # => 'Hello & <world>'
Slack::Messages::Formatting.unescape('Hey <@U024BE7LH|bob>, did you see my file?'))
  # => 'Hey @bob, did you see my file?'
Slack::Messages::Formatting.unescape('Hey <@U02BEFY4U>'))
  # => 'Hey @U02BEFY4U'
Slack::Messages::Formatting.unescape('This message contains a URL <>'))
  # => 'This message contains a URL'
Slack::Messages::Formatting.unescape('So does this one: <|>'))
  # => 'So does this one:'
  # => 'Bob'
Slack::Messages::Formatting.unescape('Hello <@U123|bob>, say hi to <!everyone> in <#C1234|general>'))
  # => 'Hello @bob, say hi to @everyone in #general'
Slack::Messages::Formatting.unescape('Hello <@U123|bob> &gt; file.txt'))
  # => 'Hello @bob > file.txt'
  # => '"hello"'
  # => "'hello'"
Slack::Messages::Formatting.escape('Hello & <world>')
  # => 'Hello &amp; &lt;world&gt;'

Command-Line Client

The slack command-line client returns JSON data from the Slack API.

Authenticate with Slack

$ slack --slack-api-token=[token] auth test

Send a Message

export SLACK_API_TOKEN=...
$ slack chat postMessage --text="hello world" --channel="#general"
{"ok":true,"channel":"...","ts":"...","message":{"text":"hello world","username":"bot","type":"message","subtype":"bot_message","ts":"..."}}

Get Channel Info

$ slack conversations info --channel=#general
{"ok":true,"channel":{"id":"C04KB5X4D","name":"general", ...}}

List Users

Combine with jq, a command-line JSON parser.

$ slack users list | jq '.members | map({(.id): .name})'
    "U04KB5WQR": "dblock"
    "U07518DTL": "rubybot"

See slack help for a complete command-line reference.

Enterprise Support

Available as part of the Tidelift Subscription.

The maintainers of slack-ruby-client are working with Tidelift to deliver commercial support and maintenance. Save time, reduce risk, and improve code health, while paying the maintainers of slack-ruby-client. Click here for more details.


This gem is based on slack-ruby-gem, but it more clearly separates the Web and RTM APIs, is more thoroughly tested and is in active development.





Copyright and License

Copyright (c) 2015-2021, Daniel Doubrovkine, Artsy and Contributors.

This project is licensed under the MIT License.