How to build a custom Slack slash command using Express and Node.js

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.

Table of Contents

• Slack “slash commands”… Wait, what?
• Building a URL shortener slash command
• Create a new Slack application
• The integration flow
• Application architecture
• Preparing the project
• The command parser
• Validation module
• The Rebrandly API Client module
• The slash command module
• Web server with Express
• Local testing with Ngrok
• Publishing the integration on Heroku
• Wrapping up

Slack “slash commands”… Wait, what?

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 everytime 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 personalised short urls with a versatile syntax. For example, we want the following command to generate the shorturl [http://loige.link/rome17](http://loige.link/rome17):

/urlshortener create a short url for the link http://loige.co/my-universal-javascript-web-applications-talk-at-codemotion-rome-2017/ using the 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 organisation 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 organisation

Now the command is linked and can be already used in your slack organisation, 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 not of your because you will need it later on.
• text: the full text passed as argument to the slash command
• team_id: the Slack id of the team where the slash cammand 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).

1. 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 web server 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 it 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 extract 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 use 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 reiceves 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 informations 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](https://www.npmjs.com/package/string-tokenizer) and some regular expressions:

• The module [url-regex](https://www.npmjs.com/package/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 cleanup 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 organised 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.

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 needs 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 to reach 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 it’s parts.

The Rebrandly API allows to create one short URL at the 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 abstraction:

• createShortUrlFactory: that allows to create 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 details is that both functions here are implementing the factory function design pattern. Both functions are used to create two new functions were that contains the Rebrandly apikey in their scope, this way you don’t need to pass the API key around everytime you want to create a short url and you can reuse and share the generated functions.

With all these details in mind, undestanding 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](https://www.npmjs.com/package/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: `** ():\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, that allows us to combine different modules in a very versatile way. This patterns offers many advantages, like:

• Keep modules decoupled.
• Allow to switch 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 leass, reads like this:

1. Verify if the current message body is present (otherwise stop and return 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 error message.
3. Use the commandParser to extrapolate information about the meaning of the current 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 urlencoded 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 shutdown 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 test 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 permanently available for your Slack team it’s time to move it online. Generally for those kind 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 an 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 and 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!

Wrapping up

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 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 in 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 creatins with me in the comments here, I might want to add some new integration in my Slack team!

#node-js #express #javascript