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.