Building a Slack app; Starting to Shipping in, like, an hour.

Building a REST API using Node.js, deploying to Heroku and accessing it from a slash command within Slack.

It’s the day before my wife’s birthday, and I realise, that whilst I have purchased her a gift from me, I haven’t purchased her one from our cats; a time-honoured tradition in our house for any gifting occasion.

I am a software engineer, and outside of my love for cats and my wife, I enjoy building applications of all sorts. So I figured I could probably knock some sort of tech together as a fun gift, and as we have a Slack workspace, I decided to build a little app so we could share pictures of our cats. 🐈

It was surprisingly easy. Really easy.

The real thing. Featuring Daisy, a cat.

An IDE, a terminal, Postman or similar, a GitHub account, a Slack workspace (that you are an admin of), and a Heroku account. (Some of those things may need setting up. Let’s assume you have done that part already.)

You will be working towards this:

Write a Rest API in node.js -> Test it with Postman -> Create a Heroku App -> Push code to GitHub -> Deploy to Heroku -> Set up your Slack app and slash command -> Eat cake 🎂

If all goes well you should get something like this at the end:

Some of the steps aren’t entirely necessary — you could just fork the repo, link it to Heroku and then to Slack. But as this is somewhat of a tutorial, it’s probably best to do the bits in between — running the API locally, checking it works etc, otherwise when you come to want to mess around with it, it’ll be easier said than done.

I made you a repo to fork, you can change this as much as you like. Or not. For this demo, you can leave it as is — as I’ll be referring to it throughout. So you know, make your life harder if you wish.

This is a simple/slack/hello-world REST endpoint, that when POSTed to returns back an appropriate response, and is about as simple as it can be. When you hit an endpoint (be that via Slack, Postman, Curl, GraphQL anything) you’ll get a response back. In this case, it’s set up to be a response that Slack can read and translate into a message to the user.

This isn’t a tutorial on how to write node.js or slash commands, there are plenty of those out there. I’ve even linked some at the bottom of this article.

Clone your repo git clone ... and cd path/to/folder
Install: npm i
Run:npm run start

Go to Postman, create a new request, set the HTTP method toPOST and the URL to: localhost:5000/slack/hello-world, hit send, and unless you changed it already (I did warn you), your response should be like this:

"attachments": [
"color": "#000000",
"text": "hello world!"
"response_type": "in_channel"

If you wanted to develop your API a little more, run it locally and test it with Slack; then ngrok is a great tool for this (this article goes into much more detail on this subject).

You can also write tests against the responses of your API requests within Postman too, which can be useful for developing this further.

Postman. Reliable, unlike a real Postman.

Set up your repo in GitHub (or not if you forked mine).

In Heroku, create a new application, and when prompted, set your deployment method to GitHub. You may be asked to authenticate, do that. Finally, select the appropriate repo.

This will link your newly made repo up with the Heroku app.

You will need to hit “Deploy” the first time. I’ve set mine to auto-deploy on push to master. This way, you don’t really need to touch Heroku again unless you want to see logs or whatever.

At this point, once it’s deployed, check your rest API in Postman against your Heroku URL https://{your-url} — you should get the same response as you did locally.

If you’ve had problems here, i.e. a 503, it’s worth noting you need a Procfile for Heroku. The Heroku logs are useful and will be your best place to start tracking down any problems. (There is a Procfile included in the repo provided)

ooh, fancy gif of doing that thing

The final piece of the puzzle. Go to Slack apps and “Create new app”, set it up with colours/pictures etc. For now, we’re taking the simplest route, but this API can do loads of neat things and it is really worth taking the time to play around with it.

Be more creative than me, please.

Create a new slack command — this will be linked to your Heroku API — specifically your URL https://{your-url} will essentially do the same thing you’ve done on Postman, only now, it can be triggered within your workspace!

(Don’t forget to link it up to your workspace)

Run /hello-world within a channel/conversation on your Workspace and you’ll see your newly added app! (As we’re using a free Heroku instance, the first time the app is called might take a second, don’t worry)

See, I said it was easy. And in less than an hour? Maybe? You might have eaten some cake first, but that’s your choice.

This is a super basic version of what can be done with these tools, play around, develop it further, make something cool, fun, useful, useless, anything.

I read a load of great articles and resources on this before doing this, which is where I’ve cobbled this method from, here are some:

I used this as a guide to starting — by @calvinkarundu

Heroku guide to integrating GitHub

Slack docs for setting up a slash command
Slack tool for building responses
Manage Slack Apps

Front End Tech Lead, you can find me on github @thomasparsons