Introduction

Slack is a real time messaging system. Most developers know it or even use it in daily team communication. One of Slack’s powerful features is the ability to create new APIs to enhance team’s experience and collaboration.

For now they have the following types of APIs:

1. Incoming Webhooks
2. Interactive Messages
3. Slash Commands
4. Event Subscriptions
5. Bot Users

In this series of posts I’m going to share with you how to setup a new Slack Command using Ruby and Heroku as backend service. It will be divided in 4 parts:

1. Setup the application (this post)
2. Command request authorization
3. Command validation and response
4. Sending a message to the congratulated user via Chat API

Slack commands

According to Slack documentation:

Commands enable users to interact with your app from within Slack.

There are a long list of built-in commands in slack that can be found here. They look like this:

/topic Hello world!

It starts with a slack (/), followed by the command name (topic) and an optional text (Hello world!).

The command above will setup the current room topic’s to the given text.

Designing the Command

The first thing we need to do is to design the command we want to create. For this example we are going to create a thumbs up command that congratulates any user in the team.

The command should look like this:

The congratulate command structure: /congratulate @user message.

Then, we should have two distinct actions after the command is triggered by someone else:

1. A reply message to the user who has invoked the command. It should be an OK message or an usage hint in case of not following the command structure;
2. A message to the user to be congratulated.

Also, according to Command API documentation, it’s a best practice to:

Provide a help action that explains your command’s usage.

Creating a new Slack Application

An Slack Application can use as many of it’s API features as you want. In this particular case we’re going to create a simple application that uses the Slash Commands feature.

First of all go to your’s application directory and configure a new application by hitting the “Create New App” on the right corner.

Steps to setup a new command: setup the application data and, then, create a new command

In the last form the most important fields are:

1. The command name, for instance /congratulate.

2. Request URL: it’s the endpoint to be called after the command is triggered. In this case we will setup to a new Heroku application at: https://congratulate.herokuapp.com/slack/command.

Let’s focus on the application creation for a while and we will get back to the slack API configuration at the end.

The Ruby server

The application will be composed by a simple Sinatra application responsible for handling with the slack command request.

The request cycle should have the following phases:

Request life-cycle

Input handling

For every command call Slack sends a POST message to the above configured “Request URL”.

The POST body has the following params structure:

{
  "token"=>"XXXXX",
  "team_id"=>"YYYY",
  "team_domain"=>"ZZZZ",
  "channel_id"=>"UUUU",
  "channel_name"=>"directmessage",
  "user_id"=>"U1234567",
  "user_name"=>"anderson",
  "command"=>"/congratulate",
  "text"=>"@john for his new product release! It's brilliant!",
  "response_url"=>"https://hooks.slack.com/commands/YYYY/DDDDD/HASH"
}

So, we need to setup a Sinatra app that handles this POST request with it params.

First, we must to create a Gemfile requiring Sinatra:

source 'https://rubygems.org'
ruby '2.4.1'
gem 'sinatra'

And then install the dependencies using bundler:

$ bundle install

Now, we create a basic application to handle the POST request at app.rb:

require 'sinatra'
post '/slack/command' do
  "OK"
end

And finally a config.ru file:

require './app'
run Sinatra::Application

Deploying the application at Heroku

First of all, you need to install Heroku CLI. The next step is to deploy the application at Heroku:

$ heroku login
$ git init
$ heroku git:remote -a yourappname
$ git add .
$ git commit -am "initial commit"
$ git push heroku master

If everything went well you will be able to test via curl:

$ curl --data '' https://yourappname.herokuapp.com/slack/command
OK

Installing your app to slack team

With the app deployed we can install our application to Slack:

In the Slack Application page, click on “Install App to Team” and “Authorize”

Using the command for the first time

Now everything is setup go to Slack and type:

/congratulate @someone for being such a good guy!

If everything is OK you will get this return:

Command response

Great! That’s the Sinatra application returning OK to the command caller!

Conclusion

So far we’ve setup the initial environment for our Ruby Command API application.

In the next post we’ll learn how to authorize the income request message using a Rack Middleware.

Follow the step by step coding at:

andersondias/congratulation-app

Writing Slack Command APIs in Ruby — Part 2