immosquare-slack

immosquare-slack lets a Ruby application interact with the Slack API: posting messages to channels, fetching user lists, and more. This page covers installing the gem, configuring the Slack bot token it authenticates with, the ImmosquareSlack::Channel and ImmosquareSlack::User methods it exposes, and the errors those methods raise. It requires Ruby >= 3.2.6 and a Slack app whose bot token carries the channels:read, chat:write, users:read and groups:read scopes.

Requires Ruby >= 3.2.6.

Add this line to your Gemfile:

gem "immosquare-slack"

Then execute:

bundle install

Before using immosquare-slack, you need to configure it with your Slack API token. Create an initializer file in your Ruby application (e.g., config/initializers/immosquare_slack.rb) with the following content:

ImmosquareSlack.config do |config|
  config.slack_api_token_bot = ENV.fetch("slack_api_token_bot", nil)
  config.default_channel     = "dev-team-monitoring"
  config.default_bot_name    = "immosquare bot"
end

ImmosquareSlack.config accepts three options — the token used to authenticate, and two values that act as fallbacks when a call omits them:

The two defaults let an application that always notifies the same channel avoid repeating the value at every call site.

To get your Slack API token, follow these steps:

• Go to the Slack API website.

• Click on "Create New App".

• Fill in the required information and click on "Create App".

• In the "OAuth & Permissions" section, you will find your API token.

• Be sure to add the following scopes to your app: channels:read, chat:write, users:read, groups:read in the Bot Token Scopes section.

ImmosquareSlack::Channel.list_channels retrieves every channel of the workspace — public and private, archived included.

ImmosquareSlack::Channel.list_channels

The result is memoized for the lifetime of the process, so a long-running Puma worker or Sidekiq process keeps serving the list it fetched on its first call. A channel created or renamed afterwards is absent from it. Pass force: true to drop the cache and refetch:

ImmosquareSlack::Channel.list_channels(force: true)

ImmosquareSlack::User.list_users gets a list of all users.

ImmosquareSlack::User.list_users

ImmosquareSlack::Channel.post_message posts a message to a specific channel. You can customize the message by using the following parameters:

ImmosquareSlack::Channel.post_message(text, channel_name: nil, notify: nil, notify_text: nil, bot_name: nil, notify_general_if_invalid_channel: true)

Parameters:

Accepted values for notify:

Example:

Using the post_message method, you can post a message in a Slack channel and customize notifications. Here's how you can use the method with all parameters:

ImmosquareSlack::Channel.post_message(
  "This is a test message",
  channel_name: "test",
  notify: ["johnDoe@mail.com"],
  notify_text: "Attention please",
  bot_name: "My Bot"
)

This will send a message to the "test" channel that looks like this:

Attention please <@johnDoe>
This is a test message

In the above message:

• <@johnDoe> is a placeholder that Slack will automatically convert to a mention of the user associated with the email "johnDoe@mail.com".

• "Attention please" is the custom notification text provided in notify_text.

• "This is a test message" is the main text of the message.

• The message will appear to be posted by the bot named "My Bot".

Shorthand with defaults:

If default_channel and default_bot_name are set in the configuration, you can omit them:

ImmosquareSlack::Channel.post_message("This is a test message", notify: :channel)

When the channel cannot be resolved:

A lookup miss can mean the channel does not exist, or that the memoized channel list predates its creation. post_message refetches the list once before concluding. If the channel is still not found:

• with notify_general_if_invalid_channel: true (the default), the message goes to the general channel instead, prefixed with immosquare-slack missing channel *<channel_name>* and notifying @channel;
• with notify_general_if_invalid_channel: false, a RuntimeError is raised.

The general channel is matched on Slack's is_general flag rather than on its name, so a workspace that renamed it is still handled.

Four situations make an immosquare-slack call raise — two when Channel.post_message cannot resolve a channel, two when Slack answers something the gem cannot use:

Apart from the single channel-list refetch that post_message performs before declaring a channel missing, nothing is retried and no error is swallowed. Wrap the call when a failed notification must not break the caller:

begin
  ImmosquareSlack::Channel.post_message("Nightly import finished", channel_name: "monitoring")
rescue StandardError => e
  Rails.logger.error("slack notification failed: #{e.message}")
end

Bug reports and pull requests are welcome on GitHub at https://github.com/immosquare/immosquare-slack. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the contributor covenant code of conduct.

Run the test suite before opening a pull request:

bundle install
bundle exec rspec

bin/ci test runs that same suite the way the CI does, and bin/ci alone chains the install and the suite. Coverage is on unless COVERAGE says otherwise, writing an LCOV report to coverage/lcov.info.

The gem is available as open source under the terms of the MIT License.