Beginners guide to building your own BotKit Slack app. Sun Tzu and Tony, Part 3

The next day, in Sun Tzu’s meditation cave

The cave is very dark and humid.
You hear faint squeaks and a water dripping in a distance.
You can’t see a thing.
After ten minutes of roaming about you notice a dim splash of light in a far distance.
You keep walking towards it for the next hour.
Finally, you reach a black silhouette illuminated by a candle flame.

Ha! At last. Come up closer my friend and sit by my side.

Today, we shall initiate you to the inner circle of enlightenment.

But before we approach the unapproachable let me ask you a question.

Are you the funny guy who drew a penis on The Elders’ Scrolls yesterday? I know panda drugged you, but limits mate. Jeeez, limits…

Speaking of panda. I’m afraid he couldn’t make it today. He made some enemies with Black Rhinos gang and he had to hide in a forest for some time. Why? I don’t know. Something about debts and koala trafficking.

[Smartphone ringing 🎶]

Wait, it’s Tony calling!

[whispers through a smarphone]

Hey, guys, I’m all right. I’m hiding in the forest. And I’m using encrypted messaging app to stay safe!

Ok, ok.

Take it easy. Head low. Make little noise. Act natural.

[hangs out the phone]

Sorry friend, this panda drives me nuts. Please, let me tell you what I planned for today:

You will learn a difference between custom Slack integration and a Slack App
You will learn how to create a Slack App, step by step;
You will learn how to configure BotKit to handle OAuth;
Lastly, you will learn how BotKit stores authentication tokens.

Let’s begin.

Difference between Slack App and Custom Slack Integration

Custom Slack integration is good for in-house solutions. For instance: you and your team use a reporting tool that only your company has access to. You wish there was a Slack chatbot sending you notifications when sales reach a certain level. And, you would like to set those levels directly from Slack using a command. You do not plan to share this integration with anyone.

It is a perfect fit for a custom integration. Sending notifications, creating commands, listening to events and building a bot are all well supported. Additionally, if you just want to create a bot, you don’t even need a web server. You can connect it to your Slack team through a WebSocket.

So, custom integration is great if you plan to make a simple tool for you and your teammates. It has limitations, though. For example, custom integrations do not support message buttons and you will not be able to upload files to Slack. This can only be done with a Slack App.

Not only Slack App covers a wider range of functionality but it also is a perfect choice if you plan to share your tool with others.

Note that Slack App isn’t limited to being a chatbot. In fact, you can create a Slack App which doesn’t include a bot. It could, for instance, be a notifications-only app.

Apps, in contrary to custom integrations, can be submitted to Slack Apps Directory.

The authentication process is also much different. In custom integration, you only need an App Token to communicate with Slack. In Slack App, on the other hand, you will need to provide an OAuth flow and ask your users to grant your app a specific set of permissions. In turn, you will receive a token. Note, that you will need to store that token somewhere. You will, most likely, need a database.

As you can see Slack App and Slack Custom Integration are quite different. The complexity of building an app is also much bigger. But, at the end of the day, it’s not really that complex.

How to create a Slack App. Steps you must take before writing any code

Before you can dive into coding, you must first declare your app in your Slack Apps dashboard.

Personally, I think the naming is a bit unfortunate here. You are essentially creating a meta description of your App. You are not writing any code. You are just setting up your app’s name, functionality scope and other properties e.g.: “OAuth redirect URL”. I would probably call it Create App Configuration.

One last important thing to note is creating a Slack App doesn’t mean you are submitting it to the Slack Directory automatically. Don’t worry, no one will know about your app unless you share it with someone 🙂

Anyway, to create an App you must first open your Slack apps dashboard.

Find a Create New App button and click it.

Fill in basic information.

Then, add a bot user.

And give it a name.

Lastly, copy and paste your Client Id and Client Secret. Later, you will copy it into the .env file.

CLIENT_ID=YOUR_CLIENT_ID
CLIENT_SECRET=YOUR_CLIENT_SECRET

1 2	CLIENT_ID=YOUR_CLIENT_ID CLIENT_SECRET=YOUR_CLIENT_SECRET

Using BotKit to create OAuth endpoints

Even though this code is available on gomix I recommend you to work on your local machine.

To get the code do the following:

git clone https://github.com/greatdaytocode-krzysztof/sun-tzu-the-wise-bot.git
cd sun-tzu-the-wise-bot
git checkout part-three
npm install

git clone https://github.com/greatdaytocode-krzysztof/sun-tzu-the-wise-bot.git

cd sun-tzu-the-wise-bot

git checkout part-three

npm install

We will not cover every aspect of this code in today’s guide. If you wish to learn how messaging works please take a look at the previous post.

Today, we shall focus on using BotKit to start a web server and create OAuth endpoints.

Look at line 24:

var controller = Botkit.slackbot({
    json_file_store: './.data/',
    debug: false,
    stats_optout: true
});

var controller = Botkit.slackbot({

json_file_store: './.data/',

debug: false,

stats_optout: true

});

This tells BotKit how to store tokens established in the OAuth process. For the purpose of this example, we will use files storage. This means that when someone connects your app with their Slack, BotKit will create a bunch of JSON files inside a .data directory (read this gomix faq to understand why .data).

If you want to deploy this code to Heroku you will need to provide your own Storage interface which reads and writes to a proper database. I will not cover it here, but it’s doable, so no worries.

Next, you must tell BotKit about your Slack App configuration.

controller.configureSlackApp({
   clientId: process.env.CLIENT_ID,
   clientSecret: process.env.CLIENT_SECRET,
   redirectUri: process.env.OAUTH_REDIRECT_URI,
   scopes: ['bot']
});

controller.configureSlackApp({

clientId: process.env.CLIENT_ID,

clientSecret: process.env.CLIENT_SECRET,

redirectUri: process.env.OAUTH_REDIRECT_URI,

scopes: ['bot']

});

clientId and clientSecret were generated when you created a Slack App (app configuration). Copy them to the .env file now.

redirectUrl is something we haven’t covered yet. It is an URL to the OAuth endpoint. Fortunately, BotKit makes it very easy to create such endpoint. We will come back to this later. For now, just leave it as it is.

scopes is an array of permissions (features) your app requests from a user connecting your app to their Slack. In this example, we only ask for a permission to add a bot.

As promised, creating a web server and OAuth endpoints is super easy:

controller.setupWebserver(process.env.PORT, (err, webserver) => {
    controller.createOauthEndpoints(controller.webserver, (err, req, res) => { })
});

controller.setupWebserver(process.env.PORT, (err, webserver) => {

controller.createOauthEndpoints(controller.webserver, (err, req, res) => { })

});

BotKit will start a server running on a PORT you can define in the .env file (do it) and it will create two OAuth endpoints:

http://YOUR_HOST_NAME:PORT/login
http://YOUR_HOST_NAME:PORT/oauth

If for instance your port is set to 3000 and your host name is slack_ninja_123 (or simply 127.0.0.1) then it will look like so:

http://slack_ninja_123:3000/login
http://slack_ninja_123:3000/oauth

Exposing your local server to the public with localtunnel

In order to build a Slack App, you must expose a public OAuth endpoint over HTTPs.

But wait! Aren’t we developing locally, and over HTTP? Yes! But, there is an easy way to run your server locally and still be able to expose it to the world over HTTPs.

We will use a nifty tool (that everyone else seems to recommend too) called localtunnel. This tool will basically make your private local server reachable from a public URL.

Follow these instructions to install and run localtunnel.

npm install -g lt
lt --port 3000 --subdomain <em>CHOOSE_A_NAME_HERE</em>

1 2	npm install -g lt lt --port 3000 --subdomain <em>CHOOSE_A_NAME_HERE</em>

When you run that second command your local server running on port 3000 (or any you’ve earlier defined in the .env file) will be publicly available as:

https://CHOOSE_A_NAME_HERE.localtunnel.me

Configuring OAuth redirect URL

We are now ready to finalise Slack App configuration.

Localtunnel provided us with a public URL we can use to set up the OAuth redirect URL.

Firstly, copy it to your .env file:

OAUTH_REDIRECT_URI=https://CHOOSE_A_NAME_HERE.localtunnel.me/oauth

1	OAUTH_REDIRECT_URI=https://CHOOSE_A_NAME_HERE.localtunnel.me/oauth

and substitute CHOOSE_A_NAME_HERE with the subdomain of your choice.

Then, visit your Slack App page and copy the same URL there:

Final step, store your users’ tokens

One would think that’s the end of story, but nope 🙁

There is one more thing we need to do before we can run and authenticate our Slack App.

Please go back to the suntzu.js file again:

var _bots = {};
function trackBot(bot) {
    _bots[bot.config.token] = bot;
}

// Triggered when you finish OAuth process
controller.on('create_bot', (bot, config) => {

    // Avoid opening a RTM connection twice for the same bot
    if (_bots[bot.config.token]) {
        return;
    }

    bot.startRTM(function(err) {
        if (!err) {
          trackBot(bot);
        }
    });

});

var _bots = {};

function trackBot(bot) {

_bots[bot.config.token] = bot;

}

// Triggered when you finish OAuth process

controller.on('create_bot', (bot, config) => {

// Avoid opening a RTM connection twice for the same bot

if (_bots[bot.config.token]) {

return;

}

bot.startRTM(function(err) {

if (!err) {

trackBot(bot);

}

});

Once the OAuth process is finished, BotKit will be notified by the create_bot event. As a result, we will finally receive a token we can use to connect our bot to Slack.

This event, however, is only triggered after OAuth process. We must also initiate bots when the application starts. Again, BotKit makes it easy.

// Connects to previously authenticated bots on app startup
controller.storage.teams.all((err, teams) => {
    for (var t in teams) {
        if (teams[t].bot) {
            controller.spawn(teams[t]).startRTM((err, bot) => {
                if (!err) {
                    trackBot(bot);
                }
            });
        }
    }
});

// Connects to previously authenticated bots on app startup

controller.storage.teams.all((err, teams) => {

for (var t in teams) {

if (teams[t].bot) {

controller.spawn(teams[t]).startRTM((err, bot) => {

if (!err) {

trackBot(bot);

}

});

}

});

There you go. We loaded all teams from a storage (currently a file storage) and spawned a bot for each team that has one.

Now! Now, we’re ready to run the app and to connect it to our Slack.

Run the local server:

npm start

npm start

Run localtunnel:

lt --port 3000 --subdomain CHOOSE_A_NAME_HERE

1	lt --port 3000 --subdomain CHOOSE_A_NAME_HERE

Visit your localtunnel login page:

Authorise your app:

Aaaand…Phew! That’s it! Your bot should be available in Slack. Try talking to him.

That’s it! Your bot should be available in Slack. Try talking to him.

How to Create a Slack App Checklist

I realise this may look tedious. And, to be honest, it is.

I have prepared a not-so-short checklist for your:

Create a Slack App/app configuration;
Add/Configure a bot to your Slack App;
Copy Client Id and Client Secret to the .env file;
Use BotKit
1. Configure BotKit storage;
2. Configure BotKit slack app with clientId, clientSecret and redirectUrl;
3. Remember about defining scopes;
4. Use BotKit to create a web server and OAuth endpoints;
5. Remember to spawn bot with a token obtained in the OAuth process;
Configure Slack App OAuth redirect URL (in your Slack apps dashboard);
Use localtunnel to expose your localhost to the public;
Run your local server;
Visit YOUR_SERVER/login page to authenticate the app.

Congratulations if you made to the end of this 3 parts guide. You learnt how to build a simple Slack bot, how to rewrite it with BotKit and, today, how to elevate it to a Slack App.

Thanks for reading!

It was great meeting you. Leave a comment below and come back for more.

The art of building bots