Create a custom Slack slash command with Node.js and Express

Introduction

In this tutorial, we are going to learn how to build and deploy a custom Slack slash command using Node.js and the Express web framework.

If you are interested in creating Slack integrations with Node.js, you might also be interested in a previous article that illustrates how to build a Slack bot with Node.js.

About the Author

Hi, I am Luciano (@loige on Twitter) and I am the co-author of Node.js Design Patterns Second Edition (Packt), a book that will take you on a journey across various ideas and components, and the challenges you would commonly encounter while designing and developing software using the Node.js platform. In this book, you will discover the “Node.js way” of dealing with design and coding decisions. I am also the co-maintainer of FullStack Bulletin, a free weekly newsletter for the ambitious full stack developer.

Slack “slash commands”

Slash commands are special messages that begin with a slash (/) and behave differently from regular chat messages. For example, you can use the /feed command to subscribe the current channel to an RSS feed and receive notifications directly into Slack every time a new article is published into that feed.

There are many slash commands available by default, and you can create your custom ones to trigger special actions or to retrieve information from external sources without leaving Slack.

Building a URL shortener slash command

In this tutorial, we are going to build a “URL shortener” slash command, which will allow us to generate personalized short URLs with a versatile syntax.

For example, we want the following command to generate the short URL `http://loige.link/rome17:

This command will require the following information:

• The command: /urlshortener
• The destination URL: http://loige.co/my-universal-javascript-web-applications-talk-at-codemotion-rome-2017/
• The URL shortener domain: @loige.link
• And the custom slashtag: ~rome17

We are going to use Rebrandly as Short URL service. If you don’t know this service I totally recommend you, essentially for 3 reasons:

1. It offers a very extensive FREE plan.
2. Has an easy to use and well documented API for creating short URLs programmatically.
3. Supports custom domains (I personally use it for my blog with loige.link and for FullStack Bulletin with fstack.link).

So, before starting the tutorial, be sure to have a Rebrandly account and an API Key, which you can generate from the API settings page once you are logged in.

Create a new Slack application

In order to create a new custom slash command for a given Slack organization, you have to create an app in the Slack developer platform.

There are a number of easy steps you will need to follow to get started:

1. Select the option to create a new slash command

2. Specify some simple options for the slash command

Notice that, for now, we are passing a sample request bin URL as Request URL so that we can inspect what’s the payload that gets sent by Slack before implementing our custom logic.

3. Install the new app in your test organization

Now the command is linked and can be already used in your slack organization, as you can see in the following image:

When you submit this command, Slack servers will send a POST request to the Request URL with all the details necessary to implement your custom logic and provide a response to the user invoking the command:

The integration flow

Before moving on, let’s understand how the data flows between the different components that make the Slack slash command work. Let’s start with a picture:

In brief:

1. A user types a slash command followed by some text (the arguments of the command) into a Slack chat window.
2. The Slack server receives the command and forwards it with an HTTP POST request to the Request URL associated with the command (hosted by the slash command developer on a separate server). The POST request contains many details about the command that has been invoked so that the server receiving it can react accordingly. Some of the fields passed by Slack to the application server are:

• token: a unique value generated by Slack for this integration, it should be kept secret and can be used to verify that the slash command request is really coming from Slack and not from another external source. Take note of yours because you will need it later on.
• text: the full text passed as an argument to the slash command
• team_id: the Slack id of the team where the slash command has been installed
• channel_name: the name of the channel where the command was invoked
• user_name: the user name of the user who invoked the command
• response_url: a special URL that can be used by the server to provide an asynchronous response to slack (useful for managing long-lived tasks that might take more than 3 seconds to complete).

3. The application server responds to the HTTP request with 200 OK and a message containing the output of the command that should be displayed to the user.

Application architecture

So it should be clear now that our goal is to implement a little webserver app that receives URL shortening commands, calls the Rebrandly APIs to do so, and returns the shortened URLs back to the Slack server.

We can break down our app into some well-defined components:

1. The web server: deals with all the HTTP nuances, receives and decodes requests from the Slack server, and forwards them to the underlying components. Collects the result from them and returns it as an HTTP response.
2. The command parser: parses the text (arguments) of the slash commands and extracts URLS, slashtags, and domains.
3. The URL shortener: uses the result of the command parser to generate the short URLs by invoking the Rebrandly APIs.

Preparing the project

For this project, we will Node.js 6.0 or higher, so, before moving on, be sure you have this version in your machine.

Let’s get ready to write some come, but first, create a new folder and run npm init in it. In this tutorial we are going to use some external dependencies that we need to fetch from npm:

npm install \
  body-parser@^1.17.2 \
  express@^4.15.3 \
  request-promise-native@^1.0.4 \
  string-tokenizer@^0.0.8 \
  url-regex@^4.0.0

Now let’s create a folder called src and inside of it we can create all the files that we will need to write:

mkdir src
touch \
  src/commandParser.js \
  src/createShortUrls.js \
  src/server.js \
  src/slashCommand.js \
  src/validateCommandInput.js

Quite some files, uh? Let’s see what we need them for:

• server.js: is our web server app. It spins up an HTTP server using Express that can be called by the Slack server. It servers as an entry point for the whole app, but the file itself will deal only with the HTTP nuances of the app (routing, request parsing, response formatting, etc.) while the actual business logic will be spread in the other files.
• slashCommand.js: implements the high-level business logic needed for the slash command to work. It receives the content of the HTTP request coming from the Slack server and will use other submodules to process it and validate it. It will also invoke the module that deals with the Rebrandly APIs and manage the response, properly formatting it into JSON objects that are recognized by Slack. It will delegate some of the business logic to other modules: commandParser, validateCommandInput and createShortUrls.
• commandParser: this is probably the core module of our project. It has the goal to take an arbitrary string of text and extract some information like URLs, domains, and slashtags.
• validateCommandInput: implements some simple validation rule to check if the result of the command parser is something that can be used with the Rebrandly APIs to create one or more short URLs.
• createShortUrls: implements the business logic that invokes the Rebrandly APIs to create one or more custom short URLs.

This should give you a top-down view of the architecture of the app we are going to implement in a moment. If you are a visual person (like me), you might love to have a chart to visualize how those modules are interconnected, here you go, lady/sir:

The command parser

We said that the command parser is the core of our application, so it makes sense to start to code it first. Let’s jump straight into the source code:

// src/commandParser.js
const tokenizer = require('string-tokenizer')
const createUrlRegex = require('url-regex')

const arrayOrUndefined = (data) => {
  if (typeof data === 'undefined' || Array.isArray(data)) {
    return data
  }

  return [data]
}

const commandParser = (commandText) => {
  const tokens = tokenizer()
    .input(commandText)
    .token('url', createUrlRegex())
    .token('domain', /(?:@)((?:(?:[a-z\\u00a1-\\uffff0-9]-*)*[a-z\\u00a1-\\uffff0-9]+)*\.[a-z\\u00a1-\\uffff]{2,})/, match => match[2])
    .token('slashtag', /(?:~)(\w{2,})/, match => match[2])
    .resolve()

  return {
    urls: arrayOrUndefined(tokens.url),
    domain: tokens.domain,
    slashtags: arrayOrUndefined(tokens.slashtag)
  }
}

module.exports = commandParser

This module exports the function commandParser. This function accepts a string called commandText as the only argument. This string will be the text coming from the slash command.

The goal of the function is to be able to extrapolate all the meaningful information for our task from a free format string. In particular, we want to extrapolate URLs, domains, and slashtags.

In order to do this we use the module string-tokenizer and some regular expressions:

• The module url-regex is used to recognize all valid formats of URLs.
• Then we define our own regex to extract domains, assuming that they will be prefixed by the @ character. We also specify an inline function to normalize all the matches and get rid of the @ prefix in the resulting output.
• Similarly, we define a regular expression to extract slashtags, which needs to have the ~ character as prefix. Here as well we clean up the resulting matches to get rid of the ~ prefix.

With this configuration, the string-tokenizer module will return an object with all the matching components organized by key: all the URLs will be stored in an array under the key url and the same will happen with domain and slashtag for domains and slashtags respectively.

The caveat is that, for every given token, string-tokenizer returns undefined if no match is found, a simple string if only one match is found and an array if there are several substring matching the token regex.

Since we want to have potentially many URLs and many associated slashtags but only one URL at the time, we want to return an object with a very specific format that satisfies those expectations:

• urls: an array of urls (or undefined if none is found)
• domain: the domain as a string (or undefined if none is specified)
• slashtags: an array of slashtags (or undefined if none is found)

We process the output obtained with the string-tokenizer module (also using the simple helper function arrayOrUndefined) and return the resulting object.

That’s all for this module.

In case you want to learn more about regular expressions, there’s an amazing article about regular expressions available here at Scotch.io.

Validation module

The goal of the commandParser module was very clear: extract and normalize some information from a text in order to construct an object that describes all the short URLs that need to be created and their options.

The issue is that the resulting command object might be inconsistent in respect to some business rules that we need to enforce to interact with the Rebrandly APIs:

• There must be at least one URL.
• There must be at most one domain per command (if none is specified a default one will be used).
• The number of slashtags cannot exceed the number of URLs (slashtags will be mapped to URLs in order, if there are more URLs than slashtags, the remaining URLs will get a randomly generated slashtag).
• A command cannot contain more than 5 URLs (Rebrandly standard APIs are limited to 10 requests per second, so with this rule, we should reasonably avoid reaching the limit).

The module validateCommandInput is here to help use ensure that all those rules are respected. Let’s see its code:

// src/validateCommandInput.js
const validateCommandInput = (urls, domain, slashtags) => {
  if (!urls) {
    return new Error('No url found in the message')
  }

  if (Array.isArray(domain)) {
    return new Error('Multiple domains found. You can specify at most one domain')
  }

  if (Array.isArray(slashtags) && slashtags.length > urls.length) {
    return new Error('Urls/Slashtags mismatch: you specified more slashtags than urls')
  }

  if (urls.length > 5) {
    return new Error('You cannot shorten more than 5 URLs at the time')
  }
}

module.exports = validateCommandInput

The code is very simple and pretty much self-descriptive. The only important thing to underline is that the validateCommandInput function will return undefined in case all the validation rules are respected or an Error object as soon as one validation rule catches an issue with the input data. We will see soon how this design decision will make our validation logic very concise in the next modules.

The Rebrandly API Client module

Ok, at this stage we start to see things coming together: we have a module to parse a free text and generate a command object, another module to validate this command, so now we need a module that uses the data in the command to actually interact with our short URL service of choice through rest APIs. The createShortUrls is here to address this need.

// src/createShortUrls.js
const request = require('request-promise-native')

const createErrorDescription = (code, err) => {
  switch (code) {
    case 400:
      return 'Bad Request'
    case 401:
      return 'Unauthorized: Be sure you configured the integration to use a valid API key'
    case 403:
      return `Invalid request: ${err.source} ${err.message}`
    case 404:
      return `Not found: ${err.source} ${err.message}`
    case 503:
      return `Short URL service currently under maintenance. Retry later`
    default:
      return `Unexpected error connecting to Rebrandly APIs`
  }
}

const createError = (sourceUrl, err) => {
  const errorDescription = createErrorDescription(err.statusCode, JSON.parse(err.body))
  return new Error(`Cannot create short URL for "${sourceUrl}": ${errorDescription}`)
}

const createShortUrlFactory = (apikey) => (options) => new Promise((resolve, reject) => {
  const body = {
    destination: options.url,
    domain: options.domain ? { fullName: options.domain } : undefined,
    slashtag: options.slashtag ? options.slashtag : undefined
  }

  const req = request({
    url: 'https://api.rebrandly.com/v1/links',
    method: 'POST',
    headers: {
      apikey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body, null, 2),
    resolveWithFullResponse: true
  })

  req
    .then((response) => {
      const result = JSON.parse(response.body)
      resolve(result)
    })
    .catch((err) => {
      resolve(createError(options.url, err.response))
    })
})

const createShortUrlsFactory = (apikey) => (urls, domain, slashtags) => {
  const structuredUrls = urls.map(url => ({url, domain, slashtag: undefined}))
  if (Array.isArray(slashtags)) {
    slashtags.forEach((slashtag, i) => (structuredUrls[i].slashtag = slashtag))
  }

  const requestsPromise = structuredUrls.map(createShortUrlFactory(apikey))
  return Promise.all(requestsPromise)
}

module.exports = createShortUrlsFactory

This module is probably the longest and the most complex of our application, so let’s spend 5 minutes together to understand all its parts.

The Rebrandly API allows to create one short URL at a time, but this module exposes an interface with which is possible to create multiple short URLs with a single function call. For this reason inside the module we have two abstractions:

• createShortUrlFactory: that allows creating a single URL and remains private inside the module (it’s not exported).
• createShortUrlsFactory: (notice Url vs Urls) that uses the previous function multiple times. This is the publicly exported function from the module.

Another important detail is that both functions here are implementing the factory function design pattern. Both functions are used to create two new functions were that contain the Rebrandly apikey in their scope, this way you don’t need to pass the API key around every time you want to create a short URL and you can reuse and share the generated functions.

With all these details in mind, understanding the rest of the code should be fairly easy, because we are only building some levels of abstraction over a REST request to the Rebrandly API (using request-promise-native).

The slash command module

Ok, now that we have the three main modules we can combine them together into our slashCommand module.

Before jumping into the code, remember that the goal of this module is to grab the request received from Slack, process it a generate a valid response using Slack application message formatting rules and Slack message attachments:

// src/slashCommand.js
const commandParser = require('./commandParser')
const validateCommandInput = require('./validateCommandInput')

const createErrorAttachment = (error) => ({
  color: 'danger',
  text: `*Error*:\n${error.message}`,
  mrkdwn_in: ['text']
})

const createSuccessAttachment = (link) => ({
  color: 'good',
  text: `*<http://${link.shortUrl}|${link.shortUrl}>* (<https://www.rebrandly.com/links/${link.id}|edit>):\n${link.destination}`,
  mrkdwn_in: ['text']
})

const createAttachment = (result) => {
  if (result.constructor === Error) {
    return createErrorAttachment(result)
  }

  return createSuccessAttachment(result)
}

const slashCommandFactory = (createShortUrls, slackToken) => (body) => new Promise((resolve, reject) => {
  if (!body) {
    return resolve({
      text: '',
      attachments: [createErrorAttachment(new Error('Invalid body'))]
    })
  }

  if (slackToken !== body.token) {
    return resolve({
      text: '',
      attachments: [createErrorAttachment(new Error('Invalid token'))]
    })
  }

  const { urls, domain, slashtags } = commandParser(body.text)

  let error
  if ((error = validateCommandInput(urls, domain, slashtags))) {
    return resolve({
      text: '',
      attachments: [createErrorAttachment(error)]
    })
  }

  createShortUrls(urls, domain, slashtags)
    .then((result) => {
      return resolve({
        text: `${result.length} link(s) processed`,
        attachments: result.map(createAttachment)
      })
    })
})

module.exports = slashCommandFactory

So, the main function here is slashCommandFactory, which is the function exported by the module. Again we are using the factory pattern. At this stage you might have noticed, how I tend to prefer this more functional approach as opposed to creating classes and constructors to keep track of initialization values.

In this module, the factory generates a new function that has createShortUrls and slackToken in the function scope. The createShortUrls argument is a function that needs to be created with the createShortUrlsFactory that we saw in the previous module. We are using another important design pattern here, the Dependency injection pattern, which allows us to combine different modules in a very versatile way. This pattern offers many advantages, like:

• Keep modules decoupled.
• Allow switching implementation of the dependency without changing the code of the dependant modules, for example, we could switch to another short URL service without the need of changing a single line of code in this module.
• Simplified testability.

Enough with design patterns and back to our slashCommandFactory function… The function it generates contains the real business logic of this module which, more or less, reads like this:

1. Verify if the current message body is present (otherwise stop and return an error message).
2. Verify that the request token is the one we were expecting from Slack (the request is very unlikely to have been forged by a third party). If the token is not valid stop and return an error message.
3. Use the commandParser to extrapolate information about the meaning of the currently received command.
4. Validate the command details using validateCommandInput (if the validation fails, stop and return an error message).
5. Use the injected createShortUrls function to generate all the requested short URLs.
6. Creates a response object for Slack containing details about every generated short URL (or errors that happened during the generation of one or more of them). For this last step, we also use the internal utility function createAttachment.

Also notice that, since the operation performed by this module is asynchronous, we are returning a Promise, and that we resolve the promise also in case of errors. We didn’t use a reject because we are managing those errors and we want to propagate them up to Slack as valid responses to the Slack server so that the user can visualize a meaningful error message.

Web server with Express

We are almost there, the last bit missing is the web server. With Express on our side and all the other business logic modules already written this should be an easy task:

// src/server.js
const Express = require('express')
const bodyParser = require('body-parser')
const createShortUrlsFactory = require('./createShortUrls')
const slashCommandFactory = require('./slashCommand')

const app = new Express()
app.use(bodyParser.urlencoded({extended: true}))

const {SLACK_TOKEN: slackToken, REBRANDLY_APIKEY: apiKey, PORT} = process.env

if (!slackToken || !apiKey) {
  console.error('missing environment variables SLACK_TOKEN and/or REBRANDLY_APIKEY')
  process.exit(1)
}

const port = PORT || 80

const rebrandlyClient = createShortUrlsFactory(apiKey)
const slashCommand = slashCommandFactory(rebrandlyClient, slackToken)

app.post('/', (req, res) => {
  slashCommand(req.body)
    .then((result) => {
      return res.json(result)
    })
    .catch(console.error)
})

app.listen(port, () => {
  console.log(`Server started at localhost:${port}`)
})

I believe the code above is quite self-descriptive, but let’s recap what’s going on in there:

1. We initialize a new Express app and activate the body-parser extension (which allows us to parse URL-encoded messages from Slack).
2. We verify if the app has been initialized with all the necessary environment variables (SLACK_TOKEN for the Slack slash command token and REBRANDLY_APIKEY for the Rebrandly API key), otherwise we shut down the application with an error. We can optionally specify also the environment variable PORT to use a different HTTP port for the server (by default 80).
3. We use our factory functions to generate the rebrandlyClient and initialize the slashCommand.
4. At this stage we are ready to register a POST route for the slash command which will just hook the parse the incoming HTTP requests and pass them to the slashCommand function we created before. When the slashCommand completes we just return its response as JSON to the Slack server using res.json.
5. Finally, we can start the app with app.listen.

That’s all, hooray! Let’s move into running and testing this Slack integration!

Local testing with Ngrok

Our app is complete and you can start it by running:

export SLACK_TOKEN="your slack token"
export REBRANDLY_APIKEY="your rebrandly API key"
export PORT=8080 #optional
node src/server

At this stage, our app will be listening at localhost on port 8080 (or whatever other port you specified during the initialization). In order for Slack to reach it, you will need a publicly available URL.

For now, we don’t need a permanent publicly available server, we just need a public URL to test the app. We can easily get a temporary one using ngrok.

After installing ngrok, we have to run:

ngrok http 8080

This command will print a public HTTPS URL.

You can copy this into your Slack slash command Request URL.

Finally, we are ready to go into our Slack app and invoke our custom slash command:

If we did everything correctly, at this stage, you should see a response from our app directly in Slack:

Publishing the integration on Heroku

If you are happy with the current status of the app and you want to have it permanently available for your Slack team it’s time to move it online. Generally for those kinds of cases Heroku can be a quick and easy option.

If you want to host this app on Heroku, be sure to have an account and the Heroku CLI already installed, then initialize a new Heroku app in the current project folder with:

heroku create awesome-slack-shorturl-integration

Beware that you might need to replace awesome-slack-shorturl-integration with a unique name for a Heroku app (somebody else reading this tutorial might have taken this one).

Let’s configure the app:

heroku config:set --app awesome-slack-shorturl-integration SLACK_TOKEN=<YOUR_SLACK_TOKEN> REBRANDLY_APIKEY=<YOUR_REBRANDLY_APIKEY>

Be sure to replace <YOUR_SLACK_TOKEN> and <YOUR_REBRANDLY_APIKEY> with your actual configuration values and then you are ready to deploy the app with:

git push heroku master

This will produce a long output. At the end of it, you should see the URL of the app on Heroku. Copy it and paste it as Request URL in the slash command config on your Slack app.

Now your server should be up and running on Heroku.

Enjoy it and keep shortening your URLs wisely!

Conclusion

So, we are at the end of this tutorial, I really hope you had fun and that I inspired you to create some new cool Slack integration! Well, if you are out of ideas I can give you a few:

• /willIGoOutThisWeekend: to get the weather forecast in your area for the coming weekend.
• /howManyHolidaysLeft: to tell you how many days of holiday you have left this year.
• /atlunch and /backfromlunch: to strategically change your availability status when you are going to lunch and when you are back.
• /randomEmoji: in case you need help in finding new emojis to throw at your team members.

… OK ok, I am going to stop here, at this stage you will probably have better ideas :)

I hope you will share your creations with me in the comments here, I might want to add some new integration in my Slack team!

Before closing off, I have to thank a few people for reviewing this article:

• Claudio Procida
• Padraig O’Brien
• Rebrandly tech team
• Andrea Mangano

Also, here are a few related links that I hope you will enjoy:

• Official Slack documentation for building apps: in case you want to understand all the capabilities of the Slack platform.
• Rebrandly custom short link api: if you want to build some other cool integration with Rebrandly.
• Node.js design patterns (my book!): in case you liked the use of the factory and the dependency injection patterns and want to learn some other cool tricks to improve the quality of your code.
• Unshorten short URLs with Node.js: an article I wrote in my blog that also goes into deep about how short URLs work, it should be a relevant read if you enjoyed the topic.
• FullStack Bulletin: a free weekly newsletter for the ambitious full stack developer (I am one of the founders and maintainers).

Cheers!