Create a Slack /command

As many other organizations — I felt in love with Slack. It’s just such a simple and powerful way to integrate external services that it’s become a must-have in my team.

Just to give you an idea, one of the Slack features I use multiple times a day is the /remind command. Not only does it help me not to forget about important things I should focus asap but also about trivial petty stuff. If you didn’t know about it, here is a complete tutorial that will help you: https://get.slack.help/hc/en-us/articles/208423427-Setting-reminders

With that in mind — I wanted to create a Slack command that allow me to replace an ordinary task I usually do at work. So, I realised, incidentally, that I take notes about many things on different places (Google Sites, Evernote, Google Keep, Google Docs, Gmail, my own notebook, etc, etc). Also, I usually share these notes along my Slack channels.

You got it, right? So I came up with the idea to create a /notes command :-)

This /notes command should help me to:

  • Create notes on any Slack channel or DM chat. So, all notes added on a channel are not private but shared among the ones that belong to the same channel.
  • Interact easily like /remind. This is one of the reasons I use this command instead of Google Calendar.
  • (Just an excuse) This command should be built using a new technology/framework I’m interested to learn.

Getting Started

First step: Understand how Slack commands work. Fortunately, the Slack documentation is clear and complete.

I grasped how Slack interacts with external services right away. You just go to your team settings and create a new command with the name you want. Next step, define the URL to which Slack will call once a user executes your command.

Then, Slack calls to your URL sending some data — in case you want to do something with that (and we definitively want!). This is an example:

token=gIkuvaNzQIHg97ATvDxqgjtO
team_id=T0001
team_domain=beerealit
channel_id=C2147483705
channel_name=general
user_id=U2147483697
user_name=ntourne
command=/notes
text=list
response_url=https://hooks.slack.com/commands/1234/5678

This data will be sent to your URL as a HTTP POST with a content-type header set as application/x-www-form-urlencoded. If you’ve chosen to have your slash command’s URL receive invocations as a GET request, no explicit content-type header will be set.

In case you want to validate if the request comes from an authorized client, then Slack sends also a Verification Token (which you define). This is really useful in terms of security.

The last step is to reply your command. In our case, we have to return the list of notes created on a channel when user triggers the /notes list command. It’s pretty straight forward! There’re two ways: We can either return a plain text string if we want to display a simple text or it’s also possible to customize the appearance of the response message using extra formatting or attachment fields through a valid JSON payload like this:

{
"text": "There are 30 notes on this channel.",
"attachments": [
{
"text":"Setup new AWS server"
},
{
"text":"Look for a WP plugin to connect to Mandrill"
},
{
"text":"Prepare status report"
}
]
}

Important: All these responses should be performed immediately (within 3000 milliseconds) with a HTTP 200 “OK” status code. If for some reason we can’t do it in real-time (for example: we should process lot of information before getting an answer), then we’re able to use delayed responses just by responding to the response_url that Slack sends in the request.

There’re some other topics worth mentioning about Slack commands but most of them are very well explained on the official documentation. If you’re interested (or just curious) about how it works, I suggest to take a look at this page: https://api.slack.com/slash-commands