Slack Ruby Client

A Ruby client for the Slack Web 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
  • Events API
    • Configuring Slack::Events
    • Verifying the Request Signature
  • Message Handling
    • Formatting Messages
      • Date and Time Formatting
      • Channel ID Formatting
      • User ID Formatting
      • Group ID Formatting
      • URL Formatting
      • Markdown Formatting
    • Parsing Messages
      • Unescaping Message Content
      • Escaping Message Content
  • Command-Line Client
    • Authenticate with Slack
    • Send a Message
    • Get Channel Info
    • List Users
• Sponsorship and Enterprise Support
• History
• Security
• Contributing
• Copyright and License

Useful to Me?

• This library lets you send messages to Slack via the Web API and facilitates integration with the Events API.
• To write a complete bot for Slack you need more than this library, and it's much easier to start with slack-ruby-bot-server-events.
• To respond to slash commands, interactive components, or events at the lowest level, 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.

Stable Release

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

Installation

Add to Gemfile.

gem 'slack-ruby-client'

Run bundle install.

Usage

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 Workflow. 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.

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']
end

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.

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 = Slack::Web::Client.new
client.auth_test

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| c.name == 'general' }

Upload a File

Upload files with sequenced API calls.

This library provides a helper method files_upload_v2 that wraps the three separate API calls.

Upload a single file.

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 (:channel_id, :channel, or :channels are all supported)
  initial_comment: 'Sharing the Q1 results :tada:', # the message that is included with the file share thread
  snippet_type: 'text', # the type of snippet
  title: 'Q1 Results', # sets the title of the file, overriding the filename
  thread_ts: '1738331487.481469' # specifies a thread to add this file to
)

Upload multiple files.

client.files_upload_v2(
  files: [
    { filename: 'report.pdf', content: File.read('/users/me/report.pdf'), title: 'Monthly Report' },
    { filename: 'data.csv', content: File.read('/users/me/data.csv'), title: 'Raw Data' }
  ],
  channels: ['#general'],
  initial_comment: 'Here are the monthly results!'
)

You can use a channel ID passed as channel_id, a single channel as channel, an array of channel IDs as channels, or a channel name or names (prefixed with #) in files_upload_v2. Lookup by name is not supported by the Slack API and this method called invokes conversations_list in order to locate the channel ID. This invocation can have a cost if you have many Slack channels and is only recommended when you intend to list channels anyway.

Note: This library includes a files_upload method that uses a deprecated endpoint files.upload that will no longer be supported on 3/11/2025.

client.files_upload(
  channels: '#general',
  as_user: true,
  file: Faraday::Multipart::FilePart.new('/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')

Other

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
client.chat_postMessage(
  channel: 'C123456',
  text: 'Hello World',
  blocks: [{type: 'section', text: {type: 'mrkdwn', text: 'Hello World'}}]
)

# As a JSON string
client.chat_postMessage(
  channel: 'C123456',
  text: 'Hello World',
  blocks: JSON.dump([{type: 'section', text: {type: 'mrkdwn', text: 'Hello World'}}])
)
client.chat_postMessage(
  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/3.0'
end

client = Slack::Web::Client.new(user_agent: 'Slack Ruby Client/3.0')

The following settings are supported.

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

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

You can 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.concat(response.members)
end
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.concat(response.members)
end
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::U