Make a Custom Slack /slash Command

The Slack channel of Switchyards, our co-working community, is a great resource to find who you need, when you need them. Need a developer, designer, or marketing guru? Find them on Slack.

But, what happens, if you don’t know everyone?

We created the /whois slash command as a custom integration for the Switchyards Slack Channel. Nerd alert: yes, we purposefully chose "whois" as an analogy to the Linux/Unix command for looking up info on a domain registrar.

By entering “/whois [slack username]” (e.g., /whois ajay), you get a nice response including details about an individual and a link to their "Mugwall" profile (shameless plug: a directory synced with Slack, also built by Standard Code).

So let’s talk about how we did this:

First, get started with a custom slash command by visting your Slack channel apps page (e.g., > Manage > Custom Integrations > Build > Slash Commands. The key points in your custom configuration are to input the API endpoint where Slack will send a request to your app, decide on a GET or POST request, and take note of the authentication Token.

We chose a GET request saying “give us a response with information from the application, but without changing any information in the database.” If you are sending information that would be saved or update the database, maybe a POST request might be more RESTful.

As a GET request, the Slack details, like the authentication Token, get appended to your API endpoint URL, like so:…

Second, parse the request at your endpoint and authenticate before sending a response back to Slack.

Remember that Token we keep talking about from your initial configuration? Use it to protect yourself from the scary internet by making a conditional check. We saved it to our ENV variables and authenticate before sending back a response:

def api-endpoint

if params[:token] == ENV['SLACK_SLASH_TOKEN']
# Run this code if the token matches
# Run this code if the token does not match

Third, respond to the Slack request with JSON, where the key/values match the Slack-required formatting for a “Message”. The Slack API has great documentation on how to format a Message, including options on adding links, images, and other attachments.

For example, our success response looked something like this:

success_response = {
response_type: "ephemeral",
text: "Success! We found @#{params[:text]} on Mugwall:",
attachments: [
fallback: member_profile_url,
color: "#390E39",
image_url: member_image_url,
fields: [
title: "Name",
value: member_name,
short: true
… #many other details
title: "Go to Mugwall Profile",
title_link: member_profile_url
status: 200

render json: success_response

A few notes on our choices.

The “ephemeral” option (rather than “in-channel”) means the response is only visible to the Slack user who sent the command, rather than to all users in the channel.

The “attachments” array is like a list of items you want to send back in the Message - in our case, the first hash are some formatted details and the second hash is a link back to Mugwall.

Overall, the Slack team did an awesome job and we were able to create this custom integration using solely the Slack API documentation.

Dec. 20 2016