slack-ruby-client: a Ruby wrapper over the Slack Web and Events APIs

What this library is, and what it explicitly is not

slack-ruby-client is a Ruby client for the Slack Web and Events APIs, and it comes with a handy command-line client too. If you are not familiar with these concepts, the README suggests watching a video on writing a first Slack bot service.

The section titled Useful to Me? is the most important part of the document for anyone evaluating it, because it draws the boundary explicitly.

The library lets you send messages to Slack via the Web API and facilitates integration with the Events API. But to write a complete bot for Slack you need more than this library, and it is much easier to start with slack-ruby-bot-server-events. And to respond to slash commands, interactive components, or events at the lowest level, the guidance is to implement a web application using your favourite web framework, use this library to call the Slack Web API, and use it to verify that events are coming from Slack.

So the division is: this gem is the API client, the event verification and the HTTP layer, and the slash command handling and interactive components are explicitly your problem, in your own web framework. That is a sensible and conventional split, and stating it up front saves the evaluation time that would otherwise go into discovering that the gem does not receive slash commands for you.

The topics confirm the scope: slack, slack-api, slack-bot, slack-bot-server, slackapi and slackbot, with hacktoberfest in the list. The primary language is Ruby, the licence is MIT, the repository is not archived, and the last push was on 2026-10-12. There are no GitHub releases, so the gem version on RubyGems is the reference point, and the README's Stable Release section is where the mismatch between the two shows up.

That section is worth reading carefully. You are reading the documentation for the next release of slack-ruby-client, and the advice is to see the documentation for the last stable release, v3.3.0, unless you are integrating with HEAD, with UPGRADING to consult when upgrading from an older version. So the master branch is ahead of what is published, and the documentation you are reading may describe a version that is not the one on RubyGems. The repository has an UPGRADING.md, a RELEASING.md and a CHANGELOG.md at the root, which is the normal release machinery for a gem that is versioned in step with the Slack API.

The repository layout shows a well-tended project: a Gemfile, a Rakefile, a Dangerfile, a .rubocop.yml with a .rubocop_todo.yml, a .rspec file, a .coveralls.yml, a .ruby-version, an AGENTS.md, a SECURITY.md, a slack-ruby-client.gemspec, and directories for bin/, examples/, lib/ and spec/.

Authentication, and the token precedence that catches people out

The authentication section has two routes, and the README is clear that one is preferred.

To integrate a bot with Slack you must first create a new Slack App. Then the OAuth Code Grant route: go to the app's Basic Info tab and grab the Client ID and Client Secret, which you need in order to complete an OAuth Workflow, and the README says OAuth v2. A working sample that starts a local web server and obtains a bot or a user token for your app using OAuth v2 is available in examples/oauth_v2.

The alternative is an API token, and the code for it is the global configuration:

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

That 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. And then the precedence rule, which is the detail worth memorising: the instance token will be used over the client type token over the global default.

Three levels of scope, in that order. A token passed to the client's constructor beats a token set on that client's Config class, which beats the global Slack.configure default. That is a sensible design, since the narrowest scope should win, but it means a global token in an initialiser file can quietly be shadowed by a per instance token, or the other way round, and the difference between a request going out with the right identity and one going out with the wrong one is invisible in the response.

The global settings themselves are a short table. token is the Slack API token, and logger is an optional logger that defaults to ::Logger.new(STDOUT) at the Logger::WARN level. So the library logs to standard output at warning level unless you say otherwise, which is worth knowing before you run it somewhere that captures stdout.

The Web client is the main entry point and it is constructed with no arguments at all:

client = Slack::Web::Client.new
client.auth_test

The auth_test call is the quickest way to confirm that your token works, and it is the first example in the documentation for a reason.

The primary language in the repository metadata is Ruby, the licence is MIT, and the gem is published on RubyGems as slack-ruby-client.

The OAuth flow, and what the sample server actually does

The OAuth route is the recommended one and it is worth understanding why, because the sample code is the clearest thing the repository contains.

The flow starts in Slack, not in your code. You create a new Slack App, then go to the app's Basic Info tab and grab the Client ID and Client Secret. You need both to complete an OAuth Workflow, and the README specifies OAuth v2.

What you need those two values for is a redirect, a token exchange and a local server, and that is why the README points at a working sample rather than describing the steps. A working sample that starts a local web server and obtains a bot or a user token for your app using OAuth v2 is available in examples/oauth_v2.

The phrase that matters is bot or a user token. Those are two different identities with different permissions, and the sample obtains one or the other depending on the scope you ask for. A bot token acts as the app, and a user token acts as a person, and the difference shows up in what the API will let you do and in what the messages look like. The as_user: true option in the chat_postMessage example is a related idea, it posts as the user rather than as the bot.

So the shape of the whole authentication story is: your app holds a Client ID and a Client Secret, a user approves the app in their browser, Slack redirects back to a URL your app owns, and your app exchanges the code for a token. The local web server in the example exists only to be the URL that receives the redirect, and the reason a sample is provided is that this part is fiddly.

The alternative is the API token, and the README is not dismissive about it, just clear that OAuth is recommended. Although OAuth is recommended, you can also generate an API token for your app and use it for some interactions. The word some is doing work there, since a statically generated token cannot be scoped or revoked per user in the way an OAuth grant can, and it has to be treated as a long-lived secret in your environment.

The environment variable convention is worth noting as a habit to copy. The example uses ENV['SLACK_API_TOKEN'] rather than a literal, which means the token is never in the source, and the global configure block means every client in the process picks it up without having to thread it through.

The OAuth v2 sample being a separate directory under examples/ alongside files_upload_v2, hi_web and new_ticket tells you something about how the maintainers think about examples. Each is a small complete program for one task, not a fragment, and the new_ticket example in particular suggests a realistic use case rather than a token hello world.

The other repository files support the same care about process. There is a .ruby-version pinning the interpreter, a .rspec for the RSpec options, a .rubocop.yml with a separate .rubocop_todo.yml for the existing offences, which is the convention that lets a project adopt a linter without a cleanup, and a Dangerfile, which is the tool that checks pull requests for the conventions the maintainer wants enforced automatically.

The Web API surface, and the file upload helper that wraps three calls

The Web client examples show the shape of the API, and it is worth noticing that the method names are the Slack method names in snake case.

Sending a message is chat_postMessage, with as_user as an option:

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

Listing channels is conversations_list, and the return value is accessed as a property on the response:

channels = client.conversations_list.channels

general_channel = channels.detect { |c| c.name == 'general' }

That chaining style, where the response object exposes the payload as a method, is the client style throughout, and it is why the file upload helper is described as a wrapper.

Uploading a file needs three separate API calls according to the Slack messaging files documentation, and this library provides a helper method files_upload_v2 that wraps them:

client.files_upload_v2(
  # required options
  filename: 'results.pdf', # this is used for the file title, unless a :title option is provided
  content: File.read('/users/me/results.pdf'), # the string contents of the file

  # optional options
  channels: ['C000000', 'C000001'], # channel IDs to share the file in

The comments are doing real work there. The filename doubles as the file title unless you pass a :title option, the content is the string contents of the file, and the channels option takes channel IDs, with :channel_id, :channel or :channels all accepted. The ability to pass a plain string rather than a file handle is worth noting, since it means the caller controls how the bytes are read.

The table of contents lists the rest of the surface: get channel info, get user info, search for a user, and a JSON arguments section, plus web client options, pagination support, character encoding, and error handling with its own subsections for Slack errors, rate limiting and other errors.

The pagination support is a practical matter rather than a nicety, because most Slack list methods are cursor based, and a client that does not handle the cursor will silently return the first page. The character encoding section and the message formatting helpers that follow are the other two places where a client library earns its keep, since Slack's message content has its own escaping rules on both the way in and the way out.

The examples directory has four working programs, and they map onto the main use cases: files_upload_v2, hi_web which is the hello world with a recording, new_ticket and oauth_v2.

Events API, signature verification, and the message formatting helpers

The Events API half of the library is where security matters, and the README has a section on verifying the request signature.

The events model has two configurations, one for the RealTime client and one for the Events API, and there is a section on configuring Slack::Events. The signature verification is the part that matters most in production, because the Events API delivers an HTTP request to a URL you expose, and without verification anyone who learns that URL can post forged events to your application.

The formatting helpers are the other substantial piece, and they are grouped by the thing being formatted. There is date and time formatting, channel ID formatting, user ID formatting, group ID formatting, URL formatting and Markdown formatting. Each of these deals with one of the places where Slack's message format has its own rules, and the naming is consistent enough that you can find the right helper by knowing what the content is.

Then there is parsing, with a sub-section on unescaping message content and another on escaping it. The pairing is the point. Slack escapes certain characters in message text, so a bot that displays raw text needs to unescape it, and a bot that sends text needs to escape it, and getting either wrong produces visible artefacts rather than an error.

The command line client section sits alongside, with sub-sections for authenticating with Slack, sending a message, getting channel info and listing users. So the same gem that you embed in a service also gives you a scriptable tool for sending a message from a shell, which is a common need for operational notifications.

The rest of the document is the business side rather than the technical one. There is a Sponsorship and Enterprise Support section, a History section, a Security section, a Contributing section, and a Copyright and License section. The Sponsorship and Enterprise Support heading in particular is worth noting, because it tells you the maintenance model of a project whose repository is under the slack-ruby organisation and whose gem is on RubyGems: there is a commercial tier, which is the usual arrangement for a library that has to track a fast moving vendor API.

For a project in that position, the question of how quickly a Slack API change reaches the gem is the practical risk, and the answer is visible in the release machinery: a CHANGELOG, an UPGRADING document, a RELEASING document and a Dangerfile, which is the tool that enforces pull request conventions on the way in.

Editorial conclusion

slack-ruby-client fits a Ruby team that wants to call the Slack Web API from a Rails or Sinatra service, or run a small script that posts a message, without writing HTTP plumbing and Slack's auth flow by hand. It is the wrong choice if you want a bot framework, since the README says a complete bot needs more than this library and points at slack-ruby-bot-server-events instead, and it is the wrong choice if you need the version on RubyGems to be the version you are reading, because the master branch documents the next release while the last stable is v3.3.0. Before adopting, read UPGRADING.md, and decide which of the two client styles you want, because token precedence differs between the global default and the per client configuration.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. slack-ruby/slack-ruby-client on GitHub