slack-ruby-client

The Web client supports automatic cursor pagination for methods like users_list. By providing a block, the client will automatically make subsequent requests using the cursor from the response until all items are retrieved.

Pagination Example

all_members = []
client.users_list(presence: true, limit: 10) do |response|
  all_members.concat(response.members)
end

Rate Limiting

When using pagination, the client automatically handles Slack rate limits by pausing and retrying based on the Retry-After header.

You can tune this behavior using:

• max_retries: The number of consecutive rate-limited responses to allow before giving up (default: 100).
• sleep_interval: A proactive pause (in seconds) between each paginated request to avoid hitting limits.

Configuring pagination parameters:

client.users_list(presence: true, limit: 10, sleep_interval: 5, max_retries: 20) do |response|
  all_members.concat(response.members)
end

To obtain a token for a specific user (rather than using a pre-configured Bot token), you must implement the OAuth v2 flow. This involves creating a Slack app, configuring redirect URLs, and handling the authorization request via a browser.

Prerequisites

1. Create a Slack app at api.slack.com.
2. For local development, use ngrok to expose your local server to the internet so Slack can send redirect requests to your machine.

Setup Steps

1. Expose local server: Run ngrok http 4242 (or your specific port).
2. Configure Slack App: Add your ngrok URL to the "Redirect URLs" section under "OAuth & Permissions" in your Slack app settings.
3. Environment Configuration: Create a .env file with the following keys:
   • SLACK_CLIENT_ID: Your App Client ID.
   • SLACK_CLIENT_SECRET: Your App Client Secret.
   • REDIRECT_URI: Your ngrok URL (e.g., https://...ngrok-free.app).
   • SCOPE: The Bot User OAuth Scopes you are requesting.
   • USER_SCOPE: The User OAuth Token Scopes you are requesting.

Running the Example

Install dependencies and run the OAuth script using dotenv to load your environment variables:

bundle install
bundle exec dotenv ruby oauth_v2.rb

After running, a browser window will open to complete the Slack authorization flow.

The Slack::Web::Client allows you to interact with the Slack Web API. You can initialize it with a specific token to override the global configuration, or use the global configuration if no token is provided.

Common Tasks

Test Authentication

Verify your token is working:

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

Send Messages

Use chat_postMessage to send text to a channel:

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

List Channels

Retrieve a list of channels using conversations_list:

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

Upload Files

Use the files_upload_v2 helper to handle the multi-step upload process required by the Slack API. This method supports uploading a single file or an array of files.

Single file upload:

client.files_upload_v2(
  filename: 'results.pdf',
  content: File.read('/users/me/results.pdf'),
  channels: ['C000000001'],
  initial_comment: 'Sharing results'
)

Multiple files upload:

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!'
)

Note: Avoid using the files_upload method as it uses a deprecated endpoint that will be unsupported after 2025-03-11.