A Ruby client for the Slack Web and RealTime Messaging APIs. Comes with a handy command-line client, too. If you are not familiar with these concepts, you might want to watch this video.
- This piece of the puzzle will help you send messages to Slack via the Web API and send and receive messages via the Real Time API.
- If you're trying to respond to slash commands, just write a basic web application and use this library to call the Slack Web API.
- If you're trying to build a Real Time bot, use slack-ruby-bot, which uses this library.
- If you're trying to roll out a full service 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.
You're reading the documentation for the next release of slack-ruby-client. Please see the documentation for the last stable release, v0.8.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 either eventmachine and faye-websocket or celluloid-io. See below for more information about concurrency.
gem 'eventmachine'
gem 'faye-websocket'
Run bundle install.
This is something done in Slack, under integrations. Create a new bot, and note its API token.
Slack.configuredo |config|
config.token=ENV['SLACK_API_TOKEN']endThis 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.
The following global settings are supported via Slack.configure.
| setting | description |
|---|---|
| token | Slack API token. |
| logger | An optional logger, defaults to ::Logger.new(STDOUT) at Logger::WARN level. |
The Slack Web API allows you to build applications that interact with Slack.
client=Slack::Web::Client.newclient.auth_testSend 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 with channels_list.
channels=client.channels_list.channelsgeneral_channel=channels.detect{ |c| c.name == 'general'}Upload a file with files_upload.
client.files_upload(channels: '#general',as_user: true,file: Faraday::UploadIO.new('/path/to/avatar.jpg','image/jpeg'),title: 'My Avatar',filename: 'avatar.jpg',initial_comment: 'Attached a selfie.')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 channels_list in order to locate the channel ID.
client.channels_info(channel: 'C04KB5X4D')# calls channels_infoclient.channels_info(channel: '#general')# calls channels_list followed by channels_infoYou 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_infoclient.users_info(user: '@dblock')# calls users_list followed by users_infoConstructs 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.
You can configure the Web client either globally or via the initializer.
Slack::Web::Client.configdo |config|
config.user_agent='Slack Ruby Client/1.0'endclient=Slack::Web::Client.new(user_agent: '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 https://slack.com/api. |
| logger | Optional Logger instance that logs HTTP requests. |
| timeout | Optional open/read timeout in seconds. |
| open_timeout | Optional connection open timeout in seconds. |
You can also pass request options, including timeout and open_timeout into individual calls.
client.channels_list(request: {timeout: 180})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=Slack::RealTime::Client.newclient.on:hellodoputs"Successfully connected, welcome '#{client.self.name}' to the '#{client.team.name}' team at https://#{client.team.domain}.slack.com."endclient.on:messagedo |data|
casedata.textwhen'bot hi'thenclient.messagechannel: data.channel,text: "Hi <@#{data.user}>!"when/^bot/thenclient.messagechannel: data.channel,text: "Sorry <@#{data.user}>, what?"endendclient.on:closedo |_data|
puts"Client is about to disconnect"endclient.on:closeddo |_data|
puts"Client has disconnected successfully!"endclient.start!You can send typing indicators with typing.
client.typingchannel: data.channelYou can send a ping with ping.
client.pingBy default, the RealTime client exposes and maintains a local store with the properties of rtm.start upon a successful connection.
| property | description |
|---|---|
| url | A WebSocket Message Server URL. |
| self | The authenticated bot user. |
| team | Details on the authenticated user's team. |
| users | A hash of user objects by user ID. |
| channels | A hash of channel objects, one for every channel visible to the authenticated user. |
| groups | A hash of group objects, one for every group the authenticated user is in. |
| ims | A hash of IM objects, one for every direct message channel visible to the authenticated user. |
| bots | Details of the integrations set up on this team. |
It also tracks changes, such as users being renamed, added or deleted, therefore client.users is always up-to-date.
Tracking with a local store can be disabled with Slack::RealTime::Client.new(store_class: nil). Other stores are also available.
The default store that tracks all changes.
A smaller store that only stores and tracks information about the bot user, but not channels, users, groups, ims or bots.
You can configure the RealTime client either globally or via the initializer.
Slack::RealTime::Client.configdo |config|
config.websocket_ping=42endclient=Slack::RealTime::Client.new(websocket_ping: 42)The following settings are supported.
| setting | description |
|---|---|
| token | Slack API token. |
| websocket_ping | The number of seconds that indicates how often the WebSocket should send ping frames, default is 30. |
| websocket_proxy | Connect via proxy, include :origin and :headers. |
| store_class | Local store class name, default is an in-memory Slack::RealTime::Stores::Store. |
| start_options | Options to pass into rtm.start, default is { request: { timeout: 180 } }. |
| 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.start. 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.
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=Slack::RealTime::Client.newclient.on:messagedo |data|
casedata.textwhen'bot hi'thenclient.web_client.chat_postMessagechannel: data.channel,text: "Hi <@#{data.user}>!"when/^bot/thenclient.web_client.chat_postMessagechannel: data.channel,text: "Sorry <@#{data.user}>, what?"endendclient.start!See a fully working example in examples/hi_real_time_and_web.
The rtm.start call downloads a large amount of data. For large teams, consider reducing the amount of unnecessary data downloaded with start_options. You may also want to increase the default timeout of 180 seconds.
Slack::RealTime::Client.configdo |config|
# Return timestamp only for latest message object of each channel.config.start_options[:simple_latest]=true# Skip unread counts for each channel.config.start_options[:no_unreads]=true# Increase request timeout to 6 minutes.config.start_options[:request][:timeout]=360endSee #134 for a discussion on this topic.
Slack::RealTime::Client needs help from a concurrency library and supports Faye::WebSocket with Eventmachine and Celluloid. It will auto-detect one or the other depending on the gems in your Gemfile, but you can also set concurrency explicitly.
Slack::RealTime.configuredo |config|
config.concurrency=Slack::RealTime::Concurrency::EventmachineendUse client.start_async instead of client.start!. A good example of such application is slack-bot-server.
client=Slack::RealTime::Client.newclient.start_asyncAdd the following to your Gemfile.
gem 'faye-websocket'
See a fully working example in examples/hi_real_time_async_eventmachine.
Add the following to your Gemfile.
gem 'celluloid-io', require: ['celluloid/current', 'celluloid/io']
See a fully working example in examples/hi_real_time_async_celluloid.
Require
All text in Slack uses the same system of escaping: chat messages, direct messages, file comments, etc. Use Slack::Messages::Formatting to unescape incoming 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 & <world>'))# => '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 <http://foo.com/>'))# => 'This message contains a URL http://foo.com/'Slack::Messages::Formatting.unescape('So does this one: <http://www.foo.com|www.foo.com>'))# => 'So does this one: www.foo.com'Slack::Messages::Formatting.unescape('<mailto:bob@example.com|Bob>'))# => '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> > file.txt'))# => 'Hello @bob > file.txt'Slack::Messages::Formatting.unescape('“hello”'))# => '"hello"'Slack::Messages::Formatting.unescape('‘hello’'))# => "'hello'"The slack command-line client returns JSON data from the Slack API.
$ slack --slack-api-token=[token] auth test
{"ok":true,"url":"...","team":"...","user":"...","team_id":"...","user_id":"..."}
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":"..."}}
$ slack channels id --channel=#general
{"ok":true,"channel":{"id":"C04KB5X4D"}}
$ slack channels info --channel=#general
{"ok":true,"channel":{"id":"C04KB5X4D","name":"general", ...}}
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.
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.
See CONTRIBUTING.
Copyright (c) 2015-2016, Daniel Doubrovkine, Artsy and Contributors.
This project is licensed under the MIT License.