Easy-Peasy Bots: Getting Started

Photo by Jeremy Waldorph

You: Have a great idea for a Slack bot, want to share it with the world (and maybe get it listed in the Slack App Directory!), and have some Javascript chops. But you don’t know where to start.

Me: Not so good at the Javascript maybe, but I know how to get the ball rolling.

So why not let’s make a bot together? 😺

In this tutorial we’ll go through prepping a very simple bot, running it on your laptop or desktop computer, and connecting it to Slack. In a future tutorial we’ll cover deploying your bot to a service like Heroku so others can use it too.

Rolling with Botkit

We’re going to use Botkit in this tutorial — Howdy.ai has done a lot (a lot) of the hard work for us, so why not leverage that?

First, we need to install some things. Make sure you have node installed on your local machine. If not, you have several options for installing node.

Begin by forking and then cloning this GitHub repository: https://github.com/slackhq/easy-peasy-bot. This is just the simplest possible project built around one of the Botkit example bots. It includes everything we need to not only write a bot, but set it up for distribution via the “Add to Slack” Button or even the App Directory, easy-peasy.

This is a Node.js project, so of course once you have the repository on your local machine, you will need to run

npm install

to install the various dependencies.

Next, edit the package.json file to give your bot a name, and to update the GitHub URLs to reflect the location of your fork.

Exposing your bot to the outside world

Bots have claustrophobia — we need to give them some light and air. Also, if the bot is holed up in the basement apartment of your local machine, Slack won’t be able to see it. So let’s open the windows a bit. Many tools will let us open a secure HTTP connection to a service running locally, such as ngrok and Pagekite. But I’m going to use localtunnel. Just use npm to install:

npm install -g localtunnel

and run localtunnel as such:

lt --port 8765 --subdomain myawesomebot

Once your bot is running on local port 8765, it will be accessible at https://myawesomebot.localtunnel.me, but your bot will only be available for testing really once it is installed on Slack. (You might consider changing “my-awesome-bot” to something more…memorable. And unique.)

Pass the good word to Slack

Now we need to let Slack know that your bot exists. Couldn’t be easier. Go to https://api.slack.com/applications/new and fill out the form. Don’t worry too much about the support URLs. But do be clear on the redirect URL. Look to the localtunnel output: The redirect URL will be https://myawesomebot.localtunnel.me/oauth

On the next page, you will see a more detailed form. Scroll down until you see the bot section:

Click on the “Add a bot to this app” button. You’ll need to provide an @-name for your bot at this point.

Finally, you need to take note of a couple of items at the top of the page: The Client ID and the Client Secret. Have those ready for the next step.

Running your bot

Now, the time has come to run your bot. From the directory your bot is installed in, simply run

CLIENT_ID=xxx.yyy CLIENT_SECRET=abc PORT=8765 npm start

And then visit https://myawesomebot.localtunnel.me/login to install your bot on a team.

Giving your bot a voice

Of course, this bot is just plain dumb. You can do better than this silly example! In index.js, look for the line

// BEGIN EDITING HERE!

and start editing away!

Botkit is structured around event listeners. The most important of these is the hears listener, which kicks off an action when your bot hears something in one of the channels to which it belongs. Let’s look at an example:

controller.hears(‘hello’,’direct_message’,function(bot,message) {
    bot.reply(message,’Hello!’);
});

This event handler is triggered when the bot receives a direct message from a user that contains the word “hello”. The bot responds in the direct message with “Hello!”.

You can listen for many kinds of messages besides direct messages: You can filter by messages that contain an @-mention of your bot, that begin with an @-mention, or simply any message at all. You can listen for any regular expression, or a list of multiple regular expressions. Bot kit is very flexible in this way.

To start with, let’s re-write this event listener to be a bit more flexible. Perhaps we want to listen for any message directed to our bot that contains different kinds of greetings. We could write:

controller.hears(
    [‘hello’, ‘hi’, ‘greetings’],
    [‘direct_mention’, ‘mention’, ‘direct_message’],
    function(bot,message) {
        bot.reply(message,’Hello!’);
    }
);

Now our bot will respond any time it sees “hello”, “hi”, or “greetings” in either a DM, or a message that @-mentions the bot. (Don’t forget to restart your bot after each edit!)

(If you’re having trouble getting your regular expressions just right, I find this online regex tester super helpful.)

Congratulations!

👏 You’ve built your first bot in Slack, and it’s not just a Hello World bot—it’s a Hi World and Greetings World bot too!

At this point you will probably want to start doing more sophisticated things, like making requests to external services, so your bot can respond with timely and useful information (depending on what your bot does, of course). There’s a lot more to Botkit than this! You can learn more about Botkit’s awesome features by simply perusing the Botkit documentation.

Next time…

Of course, you don’t want to host your bot on your laptop forever. (Or maybe you do?) Over the next articles, I will show you how easy it is to deploy your bot to hosting services like Heroku, give your bot a more permanent memory, and extend your bot’s functionality with artificial intelligence services. But at this point you should be far enough along to get your core logic going, and maybe even demo it.