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.
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.
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:
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.
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:
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:
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:
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:
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:
[url-regex](https://www.npmjs.com/package/url-regex)
is used to recognize all valid formats of URLs.@
character. We also specify an inline function to normalize all the matches and get rid of the @
prefix in the resulting output.~
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.
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:
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.
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)
).
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:
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:
commandParser
to extrapolate information about the meaning of the current received command.validateCommandInput
(if the validation fails, stop and return an error message).createShortUrls
function to generate all the requested short URLs.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.
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:
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
).rebrandlyClient
and initialize the slashCommand
.slashCommand
function we created before. When the slashCommand completes we just return its response as JSON to the Slack server using res.json
.app.listen
.That’s all, hooray! Let’s move into running and test this Slack integration!
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:
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!
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