Slack has become a popular collaboration tool across enterprises. It is a great fit for team communication in areas where Email is coming up short. The power of Slack is not just in the platform and the various clients that it provides to teams but also an open platform that allows users to integrate with popular outside applications and APIs.
The Slack API home page covers the various mechanisms that it provides for outside applications to tap into the platform and make it a hub for team communication. As per the official documentation, these mechanisms include :
- Web API
- Real Time Messaging API
- Slackbot Remote Control
- Incoming / Outgoing Webhooks
- Slash Commands
In this article we are going to look at how you can integrate slash commands into your Slack Team Portal. A slash command listens for messages in chat and looks out for trigger words. When triggered, it sends a payload to an external URL. For example say we are a team working for ProgrammableWeb and want to find out the various API Categories that are available in the directory. We could define a slash command that looks for a text trigger named /categories.
If anyone types /categories in the chat message window, then the slash command is activated. It will then invoke a backend application (external to Slack and hosted by you) and pass an API payload over HTTP to your application. The application can then process the command and return back the appropriate response.
The flow works as follows:
- Step 1 : The user types /categories as the command or they could type any other slash command or other text.
- Step 2 : The Slack application checks its slash command configuration if there is a slash command (/categories) configured or not. If it is not configured, it won’t do anything about that. If it is configured, it will know the backend application that the Slack admin has mapped it to, as part of the slash command setup.
- Step 3 : If the slash command mapping was found, the HTTP request with various parameters like token id, team id, user name, command name and more (as request parameters) are sent to the backend application, either in the form of HTTP GET or POST.
- Step 4 : The application processes it and sends back a HTTP Response that is sent back to the user client.
In the next few sections, we will take a look at how we can setup a simple slash command that does this. For the purpose of understanding the flow, the example used returns back dummy data and not some sophisticated backend processing application. That is entirely left to the reader as to what they would like to integrate into the slash commands.
Setting up a Slash Command
The first thing that we have to do is plan out which slash commands we are going to handle in our backend application and the URL that we will be mapping it too. The URL will be the actual backend application that is hosted publicly such that the Slack service can access it.
In our case here, we are going to show how to map the /categories slash command to a sample application running in the Cloud.
Assuming that you are the Administrator for your Slack team account, log in to the Slack team portal and go to Configure Integrations as shown below:
This will bring up the Configure Integrations page where you can add various integration services to your team. Since we are interested in slash commands, just type “slash” in the filter search input box as shown below:
This will bring up the slash commands service as shown. Click on View and it should bring up a form to configure the slash command.
In the choose a command form, we type in /categories as shown below:
Then click on Add Slash Command Integration button. This will bring up the detailed configuration screen for the /categories command and two sections that we will discuss now.
Outgoing Payload and Responses
The first one is the Outgoing Payload and Responses section. Here we can leave things as the default but you should understand what request parameters are going to be sent to your backend application. I am reproducing here a sample HTTP Request that gets sent to your application:
token=ItoB7oEyZIbNmHPfxHQ2GrbC team_id=T0001 team_domain=example channel_id=C2147483705 channel_name=test user_id=U2147483697 user_name=Steve command=/weather text=94070
I would classify the request parameters into the following categories:
- Team Details
- Channel Details
- User Details
- Command Details
You can and ideally should use the token to validate if the request is indeed coming from Slack and the token that you are expecting it from. Similarly, it is up to your application to use the team and user details accordingly to either validate the request or log details as needed so that authentication and authorization can be performed by your application.
Finally, for the command details, we have command and text HTTP request parameters. The command is the slash command that was typed by the user. This would be a quick way for your application to determine if it is supporting the command or not and then optionally there could be additional text parameters to the command that you could use.
For example a slash command to get tasks which are open could be /task and the text provided to it would be “open” i.e. the status.
In this section, we do the mapping of the slash command to the URL that will be invoked. Additionally, you can also set the HTTP method i.e. GET or POST. You will also notice that the token value is passed in the payload and you can regenerate it (if needed).
I have set the URL in the sample screen below to a URL where my application is being hosted. In my case, it is hosted on Google App Engine (which we will see a bit later) and I have just put in a dummy URL.
But since you can host your backend in any development stack that you want (Java, Python, PHP, etc) -- all you need to specify here is the URL of your public web application that will be invoked by the Slack service.
Additionally, I suggest to turn on the setting for Autocomplete Help Text. This will help show the commands to the user when they are using the client to message. The values for our sample command are shown below:
Remember to click the Save Integration button at the bottom.
You can go back to the list of integrations for your team. The slash commands integration should now appear in the list with our configured command as shown below:
If you run into any issues with the configuration, check out the official guide for slash commands Integration.
Creating your Project in Google Cloud
Now it is time to write our backend application. I am going to go with Google App EngineTrack this API, which is a Platform as a Service (PaaS) available from Google. It allows you to deploy your web applications written in Java, Python, Go or PHP and does all the heavy lifting for you in terms of the infrastructure provisioning and running your application for you.
The first thing that you will need is a Google Cloud Project. To do that, follow these steps:
1. Ensure that you have a Google Account.
2. Go to https://console.developers.google.com and click on Create Project.
3. This will bring up the New Project window and you should type in a Project Name that you like. In my case I put in MySlash as shown below:
4. Important : Note down the project ID that it generates. A project ID is a unique way in which the applications will be identified by the Google Cloud. They are unique across all projects.
5. So in the case of the App Engine environment, which is where we are going to be hosting our application, the URL for our application is going to be of the following format:
So in my case, it will be http://myslash-1058.appspot.com
6. This will be the URL that I will put in the slash commands Integration Settings page that we saw earlier. Make sure that is accurate, otherwise Slack will not be able to reach out to the correct hosted application.
7. Click on the Create button to complete the task of creating the project in Google Cloud. The Project will then appear in the list of projects.
We do not need to do anything further at this point with Google Cloud Console.