Slack Slash Command Tutorial

This is a step-by-step tutorial on how to get started with writing a Slack Slash Command.

A Slack Slash Command is one of the ways that you can write your own Custom Integration with Slack and is probably the simplest way to plug in some custom functionality into your Slack Team. If you would like to know what a Slack Slash Command is, I strongly recommend the initial section on “What are slash commands?” in the official Slack API documentation.

Employee Lookup Slash Command

The Slash command that we want to implement is to provide Employee Information. Imagine if you had the employee number or id and wanted to lookup the information about the employee in the organization i.e. employee name and phone number extension, etc.

So all one needs to do inside of slack is to give a command in the chat text box as follows:

/lookup <EmployeeId>

This should then lookup the Employee Directory application and provide us the results i.e. Employee Name, Employee Phone Number Extension. The final result is shown below:

Result of /lookup E1

Employee Lookup Slash Command — The Code

We will write our slash command in Go Language and will be deploying it on Google App Engine. You can read more about Go Language support on Google App Engine.

There is a single file named employeelookup.go. The code listing is given below:

Let us go through the code in brief:

1. The Employee Data that we need to lookup in this case is not from an actual database but to keep the focus on writing a Slash command, I have taken the liberty to use a map data structure and have hard-coded the data to just 3 records as you can see on lines 8–12.
2. We map a Web Request handler function named handler to a URI i.e. “/”
3. The Web Request handler function (handler) extracts out the command and the text request parameters. Slack passes the Slash Command that we configure (/lookup) as the value in the command request parameter. It also passes the rest of the text following the slash command in the text parameter.
4. We do some simple checks on the command parameter and then lookup the map for the employee record, returning it if found. Some basic error handling has also been implemented.

Ideally you would want to put in some more strict data validation here to ensure that the token that is passed by Slack is also validated. But I have intentionally kept it simple for now.

While I have chosen Go Language as my preferred language, you can see that if you are proficient in any Server side language like Java, Python, PHP, C# and are familiar with writing a Web Request / Response handler, you are good to go with that language/framework.

You need one more file which is the application configuration file as shown below:

This is standard App Engine deployment descriptor (app.yaml) and while we can put the project id and version in here, I have kept it out so that we can provide it when we deploy the application. You can read more about it here.

The complete code is hosted on Github.

rominirani/slack-slash-command

Employee Lookup Slash Command — Deployment

We are going to be using Google App Engine for hosting our Slash Command. You could chose to host it on another provider if you want.

Assuming that you have signed up for Google Cloud Platform, follow these steps:

1. Visit Google Cloud Console at https://console.cloud.google.com with the account that you have signed up for.

2. Click on Create a project at the top and in the dialog window, enter a name for the project. For e.g. my-slashcommand as shown below:

Note down the project ID since this is unique across our Google Cloud Platform projects.

3. The next step is to deploy the application to Google Cloud App Engine environment via the gcloud app deploy command.

4. Go to the root of the project directory where you have cloned the Github application and in which the files app.yaml and employeelookup.go are present.

5. Give the following command:

gcloud app deploy

This will deploy the application for your project id.

You should see a sequence of activity as shown below:

Creating App Engine application in project [<your-project-id>] and region [us-central]....done.
Services to deploy:
descriptor:      [/Users/romin-irani/Documents/SlackBlog/slack-slash-command-master/app.yaml]
source:          [/Users/romin-irani/Documents/SlackBlog/slack-slash-command-master]
target project:  [<your-project-id>]
target service:  [default]
target version:  [20171228t074516]
target url:      [https://<your-project-id>.appspot.com]
Do you want to continue (Y/n)?  Y
Beginning deployment of service [default]...
╔════════════════════════════════════════════════════════════╗
╠═ Uploading 4 files to Google Cloud Storage                ═╣
╚════════════════════════════════════════════════════════════╝
File upload done.
Updating service [default]...done.
Waiting for operation [apps/<your-project-id>/operations/c486cd4b-a9c5-4188-99ac-3fe9507b256b] to complete...done.
Updating service [default]...done.
Deployed service [default] to [https://<your-project-id>.appspot.com]

The application is now available at:

https://<your-project-id>.appspot.com

Employee Lookup Slash Command — Configuring Slack

Now that we have deployed our application to App Engine runtime, the final step is to configure this Slash Command inside our Slack Channel. The steps for that are as follows:

1. You need to be an Administrator for your Slack Team and have logged in to your Slack Team.
2. Go to https://<your-slack-channel-name>/apps/manage
3. Select Custom Integration from the options since we are only going to make this for our team.

4. You will be shown a list of different Custom Integrations that you can do. Slash command will be one of them, click that.

5. In the Choose a Command screen that comes up, enter /lookup and click on Add Slash Command Integration.

6. This will open up a detailed configuration screen for the /lookup command and you need to go down to a section that is titled Integration Settings and enter the values as shown below:

Note that the YOUR_PROJECT_ID value in URL field is the your Google Cloud Platform project ID that you created earlier.

7. It is nice to select a Custom Icon and Autocomplete Help Text for your Slash command.

8. Finally click on Save Integration.

This completes your Slash Command configuration for your Slack Team and you should be able to see it listed when you start entering /lookup in the chat text field.

Employee Lookup Slash Command — In Action

Now that we have deployed our Slash command and configured the Custom Integration for our Slack Team, all we need to do is to see in action.

The format of the Slash command is:

/lookup <EmployeeId>

Since our data samples are limited (just 3 Employee records with Ids 1 , 2 and 3), we try it as shown below:

This invokes our Slash Command handler that is hosted in Google App Engine and it comes back with a response.

Moving Ahead

The goal of this article was to show you the entire mechanics around writing and configuring Slash Commands. They can be very powerful for your team if integrated with the right backend APIs that you would have.

All the best writing your custom Slash Commands.