DEV Community: Tom Quirk

Create a Slack Bot with Node.js: The Definitive Guide

Tom Quirk — Sat, 09 Oct 2021 06:10:17 +0000

If this is the millionth article you've found on how to build a Slack bot with Node.js, I'm sorry.

I've built a few Slack bots, some of which have launched on the Slack App Directory. I'm going to give you a no-bullshit tutorial on creating a Slack bot with Node.js.

We'll build an internal tool that your team can use to get information about your customers using a slash command. I'm not going to teach you how to build a Slack app for the Slack App Directory.

Quick plug: if you want to skip this entire article and focus on writing your internal tool, try Runtime.

Set up Ngrok

Ngrok is how you'll connect your Slack workspace (on the internet) to your locally-running Slack bot (on your machine). It has a free plan, but the Basic plan is affordable and extremely useful for building Slack bots.

Security note: Ngrok exposes your machine to the internet, making it a potential attack vector. If you're building your Slack bot on your work machine, get Ngrok approved by your security team.

Create an Ngrok account and follow the set-up steps. When you're finished, expose a web server on port 8080:

ngrok http 8080

This should produce the Ngrok console UI:

ngrok by @inconshreveable

Tunnel Status                 online
Version                       2.0/2.0
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://92832de0.ngrok.io -> localhost:8080
Forwarding                    https://92832de0.ngrok.io -> localhost:8080

Connnections                  ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

If you're on the free Ngrok plan, don't close this terminal window. The forwarding URL is randomly generated, and will change when you restart Ngrok.

Take note of the Forwarding URL. In the example above, it is: https://92832de0.ngrok.io.

Set up your Slack app

Before we start writing code, we need to create a Slack App.

Navigate to https://api.slack.com/apps?new_app=1.
Select From an app manifest.
Replace <NGROK_FORWARDING_URL> with your Ngrok forwarding URL in the App Manifest YAML file below.

In the Ngrok example above, we would use https://92832de0.ngrok.io. So, the redirect_urls example below would become: https://92832de0.ngrok.io/slack/oauth_redirect

Copy-paste the YAML contents in the Enter app manifest below section.

_metadata:
  major_version: 1
  minor_version: 1
display_information:
  name: NodeBot
  description: Our internal Slack bot.
features:
  bot_user:
    display_name: NodeBot
    always_online: true
  slash_commands:
    - command: /customer
      url: <NGROK_FORWARDING_URL>/slack/events
      description: Get data about a customer
      usage_hint: /customer <customer id>
      should_escape: false
oauth_config:
  redirect_urls:
    - <NGROK_FORWARDING_URL>/slack/oauth_redirect
  scopes:
    bot:
      - commands
      - chat:write
      - chat:write.public
settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

App Manifest for your Slack bot

Select Next, then select Create.

Scroll down to the **App credentials **section and take note of the following values:

Client ID
Client secret
Signing secret

Finally, install the app to your Slack workspace.

Select Install App on the left sidebar.
Select Install to Workspace, and select Allow on the installation page.
Take note of the Bot User OAuth Token.

Set up your Slack bot code

Let's ensure your local environment is set up correctly. The dependencies for this Slack bot are as follows:

node >=12.13.0
npm >=6.12.0

Start by creating a new directory for the Slack bot and initialising npm:

mkdir slackbot-node
cd slackbot-node
npm init

Follow the prompts (tip: hold down the Enter key).

Let's install the project dependencies. Our main dependency is Bolt, the official Slack framework for building Slack apps with JavaScript.

npm install --save @slack/bolt dotenv
npm install --save-dev nodemon

Add your environment variables

Create a .env file.
Add the following contents to your .env file, and add the values you took note of in the Set up your Slack app section.

SLACK_CLIENT_ID=<YOUR SLACK CLIENT ID>
SLACK_CLIENT_SECRET=<YOUR SLACK CLIENT SECRET>
SLACK_SIGNING_SECRET=<YOUR SLACK SIGNING SECRET>
SLACK_BOT_USER_TOKEN=<YOUR SLACKBOT USER TOKEN>
SLACK_OAUTH_STATE_SECRET='my-state-secret'

Create the bot server

Create an index.js file. This will be the entry point for our bot server.
Copy-paste the following code:

require("dotenv").config();
const { App } = require("@slack/bolt");

const port = process.env.PORT || 8080;

const app = new App({
  token: process.env.SLACK_BOT_USER_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
});

// Slash command handler goes here.

(async () => {
  await app.start(port);

  console.log(`🤖 Slack bot at your service (http://localhost:${port})`);
})();

Check the server works by starting the bot server with nodemon.

nodemon restarts the server whenever we edit our index.js file

nodemon --exec node index.js

You should get the following output:

[nodemon] 2.0.13
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `node index.js`
🤖 Slack bot at your service (http://localhost:8080)

Add a slash command

The App Manifest file that we used to create our Slack app has already added a slash command for us; it's called /customer. Whenever somebody in your Slack workspace types /customer, Slack will send a POST request to your bot server; we need to program our bot server to respond correctly to the /customer slash command.

Add the following code to index.js:

// Handle the /customer slash command
app.command('/customer', async ({ command, ack, respond }) => {
  // Acknowledge command request
  await ack();

  await respond('Slack bot at your service!');
});

Now, we can test the slash command in Slack. Type /customer in Slack. This should yield the following result:

Getting customer data

Finally, the juicy part. The method for getting customer data will vary based on your tech stack and where your customer data lives. Typically, you'll execute a database query here. For now, let's return some dummy user data.

Format your response with the Slack Block Kit Builder.

const customerData = {
  name: "Jane Doe",
  email: "jane@company.com",
  activeUsers: 10,
  plan: "Enterprise",
  totalSpend: "$1002.26",
};

// Format the text however you like; Slack supports Markdown.
const header = `*${customerData.name}* (${customerData.email})`;
const body = `>${customerData.plan} plan\n>${customerData.activeUsers} users\n>${customerData.totalSpend} total spend`;

const response = {
  response_type: "in_channel", // make the response public
  blocks: [
    {
      type: "section",
      text: {
        type: "mrkdwn",
        text: `${header}\n${body}`,
      },
    },
  ],
};

await respond(response);

Let's run it in Slack and see the result. Type /customer in Slack:

Building and maintaining internal Slack bots is a hassle. I built Runtime to help you rapidly create custom Slack bots. Write your internal script in your technology of choice, and Runtime handles the rest. Let me know what you think on Twitter.

5 reasons why Slack will reject your Slack app

Tom Quirk — Fri, 09 Oct 2020 23:38:02 +0000

At a time when businesses are increasingly relying on Slack for day-to-day operations, the Slack App Directory is thriving. These days, there are Slack apps for everything: from polls to team recognition, to daily standups, to promoting inclusive language. There has never been a better time to be a Slack user.

Likewise, there has never been a better time to create a Slack app!

But it's not all sunshine and roses. I've been through the Slack app process twice, first with UPPIT and now with AllyBot. Building a Slack app is fun and Slack is always improving the developer experience. But, there are a few gotchas that have cost me a lot of time during the review process.

Here are 5 reasons why Slack will reject your bot, and what you can do about it.

1. Security

Do yourself a favor and use bolt.js. This one might be obvious, but it certainly wasn't to me when I built UPPIT. Don't get me wrong, you can build a basic Slack app with the Slack web API and your backend framework of choice; this is what I did with UPPIT.

But when you go to submit your app to the Slack App Directory, you will soon realize there are a bunch of security things you probably didn't consider. OAuth and token management, and verifying requests from Slack and the ones I've failed with in the past. Both these topics deserve an article, but the takeaway is that bolt.js handles a lot of this stuff for you. It provides sensible interfaces and callbacks for the things you need to customize. It also provides simple wrappers for the Slack web API out of the box. bolt.js an obvious choice that allows you to focus on building your app.

I estimate 20% of the time I spent on UPPIT was on these auxiliary tasks, whereas when I used bolt.js for AllyBot, it was more like 5%.

Don't reinvent the wheel - use bolt.js!

2. No customer support or poor branding

When you're in the trenches building your app, it's easy to forget that you need to market the thing! Slack requires a bunch of items on this front. Let's go through some of the ways you can succeed on this front.

Privacy policy and Terms of Service

Slack will not accept your app without a link to a Privacy Policy and a Terms of Service. It's best to seek legal advice, but you can also get pretty far by using existing Slack apps as inspiration.

Support email address and contact form

You need an email address for support and a support page on your website. For email, I use Zoho. It's free, and I've set up tom@allybot.io, and a "catch-all" alias that points to tom@allybot.io. This means I can list my app's support contact as something like support@allybot.io and I'll receive any emails sent there at tom@allybot.io.

For the support page, a simple contact form does the job - check out https://allybot.io/#support for an example (built with https://carrd.co).

Add to Slack button

Make sure your website has an Add to Slack button. If you're using bolt.js, link this button to https:///slack/install. Redirect the user to an "Install Successful" page once they've successfully installed your app (Slack requires this).

Branding

Slack has a bunch of resources on this topic, but the bottom line is this: keep your branding consistent and don't conflict with Slack's branding. Simple!

3. Bad use of the App Home

Utilizing the App Home in Slack can be confusing, but this is a must-do. Slack has a whole article on this, but here are some essentials.

Send the user who installed your app an intro message

When a user installs your app, you need to send them a message that explains to them how to get started. Here is AllyBot's welcome message:

Of course, make sure you only send this once.

Respond to app_home_opened event

When a user other than the user that installed your app opens your apps App Home tab, you need to greet them as well! Again, this should only be a once-off. I have a flag for app_home_opened in the user table of the database, set to false. When the user first opens the App Home tab, this flag flips to true so I know never to send the message to the user again. The message can be like the first one, for example, this is how AllyBot.io responds to app_home_opened:

Note that you will need to request the im:write scope to start chats with users.

4. Not giving good reasons for your requested OAuth scopes

This is a common reason Slack apps get held up in the review process. You should take the time to consider if your app needs all the scopes you are requesting. Slack will reject anything that seems like a "nice to have".

Give genuine reasons about why you need a certain scope. And be transparent. If you are capturing user emails (with the users:read.email scope), then say so.

The same applies to your data retention policies. Don't simply say "We will retain your data as per our privacy policy". Give a short, clear and concise description about how you plan to handle your user's data. Something like "When you ask us to delete your data, we will respond to you via email by 24 hours. We will aim to fulfill your data removal request with 24 hours of responding, and will inform you when your data has been removed. For more information, see our Privacy Policy".

5. Poor error handling

During the review process, Slack will try and break your app. But don't see this as a negative; we should be super grateful to get free QA testing (thanks Slack)! Using bolt.js will help you here. But, if your Slack app uses slash commands, or "actions" (buttons, etc.), think carefully about where your app could fail.

Make sure to send the user a message when errors occur. An "ephemeral" message is a good way to do this; an inline, private message to the user interacting with your app. Something as simple as "Oops, something went wrong 😢" is a good start, but always try to give direction to the user.

Ask me anything

Have I missed something? Need something clarified? Hit me up on Twitter @tom__quirk.