Slackathon

A simple way to build Slack interations inside a Rails app. Check out our
blog post for the story behind
this gem!

Installation

Add this line to your application’s Gemfile:

gem 'slackathon'

Also, add this to config/routes.rb

mount Slackathon::Engine => "/slack"

And then execute:

$ bundle

Development Workflow

Basic Slack Command

1. Set up https://ngrok.com/

   This gives you a public URL for Slack to reach your development machine.
   On a Mac, you can also install it via brew cask install ngrok.

   Assuming the Rails app is already running on port 3000, you can expose the
   Rails app with ngrok http 3000, which should give you a public URL like
   http://00bea6f5.ngrok.io.

2. Create a Slack app at https://api.slack.com/apps

   The “App Name” will be used as the display name when the app is replying to
   commands.

   To get everything working perfectly, you probably want to mirror all the
   settings on the production app, the here are the most important bits.

3. Go to “Your App > Settings > Install App” to add it to your Slack.

4. Create your command under “Your App > Features > Slash Commands”

   • The command is whatever you would type after the “/“ in Slack, e.g.
     /monkey.
   • The request URL should be http://00bea6f5.ngrok.io/slack/commands.
   • You probably want to turn on “Escape channels, users, and links sent to
     your app” which will make it easier to parse @mentions and #channels.

5. Create a monkey_command.rb in app/slack

   • The name of the file (monkey_command.rb) and the class name (MonkeyCommand)
     has to match the name of the command (/monkey).
   • You should inherit from the Slackathon::Command class.
   • You have access to the params hash.
   • At minimum, you will need to implement the call method.

   • Example:

     class MonkeyCommand < Slackathon::Command
       def call
         {
           response_type: "in_channel",
           text: "#{user} said #{params[:text]} "
         }
       end
       private
       def user
         "<@#{params[:user_id]}>"
       end
     end

   • See https://api.slack.com/slash-commands#responding_to_a_command and
     https://api.slack.com/docs/message-formatting for more documentation about
     the responses you can send.

Adding Buttons

In this section, we will modify the MonkeyBot and let the user pick which
monkey emoji to use.

1. Enable “Your App > Features > Interactive Components”

   • This is required to support buttons, menus and dialogs.
   • The request URL should be http://00bea6f5.ngrok.io/slack/interactions.
   • You probably won’t need to worry about “Options Load URL”.

2. Instead of immediately posting to the channel, we will reply to the user
   only, asking for their emoji preference:

   class MonkeyCommand < Slackathon::Command
     def call
       {
         response_type: "ephemeral",
         attachments: [{
           callback_id: "monkey",
           text: "Please pick a style",
           actions: [{
             type: "button",
             text: "Click to use ",
             name: "post_in_channel",
             value: "#{params[:text]} "
           }, {
             type: "button",
             text: "Click to use ",
             name: "post_in_channel",
             value: "#{params[:text]} "
           }, {
             type: "button",
             text: "Click to use ",
             name: "post_in_channel",
             value: "#{params[:text]} "
           }]
         }]
       }
     end
     def post_in_channel(value)
       # do something with value, see below...
     end
   end

   • Here, we are using the ephemeral response type (as opposed to in_channel
     as we did previously), which makes the response visible only to the user
     who sent the command.
   • In addition to the message text, we are including a few buttons in the
     attachments array.
   • The callback_id need to match the name of your command (e.g. monkey in
     this case).
   • The actions array has the button(s) you want to include.
   • The text is the label of the button (e.g. “Click me!!!”).
   • The name is the name of the method to call when the button is clicked
     (see below).
   • The value is an optional string that will be passed to the method (see
     below).
   • See https://api.slack.com/interactive-messages and https://api.slack.com/dialogs
     for more documentation.

3. When the user clicks on one of the buttons, it will call the method you
   specified:

   class MonkeyCommand < Slackathon::Command
     # def call ...
     def post_in_channel(value)
       {
         response_type: "in_channel",
         delete_original: true,
         text: "<@#{params[:user][:id]}> said #{value}"
       }
     end
   end

   Here, value is the string that we attached to the original buttons.

Promoting to Production

1. Remove the command from your development Slack app.

2. Create a production Slack app and your command/interactive component
   following the instructions above (with the URLs pointing to your
   production Rails app).

3. Find the “Verification Token” from https://api.slack.com/apps/<your app>.
   Assign its value to the SLACK_VERIFICATION_TOKEN ENV variable in
   your production environment (or set it with Slackathon.verification_token = ...).

4. Make sure your Active Job adapter is configured to process the slack
   queue (e.g. bundle exec sidekiq -q default -q slack ...). Alternatively,
   you can change the queue with Slackathon.queue = ....

5. Deploy your changes!

License

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