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., https://your-channel.slack.com/apps) > 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:


https://your-secure-domain.com/api-endpoint?token=gIkuvaNzQIHg97ATvDxqgjtO&team_id=T0001&…


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
...
else
# Run this code if the token does not match
...
end
end


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.
Picked by Ajay
Dec. 20 2016
note