README
slack-express
Quickly implement a Slack slash commands as Express middleware.
hello world
Define a handler for /echo
slash command:
import slack, {slash, start} from 'slack-express'
slash('/echo', (payload, message)=> {
// payload recieved as a POST from Slack command issued
let cmd = payload.raw.command
// sends a response to the Slack user
message({text:`Received command from Slack: ${cmd}`})
})
start()
Now any Slack user issuing /echo
slash command will recieve "Received command from Slack: /echo" message.
generated routes
Under the hood slack-express
is just an Express app that generates Slack API friendly routes for authenticating an app and recieving incoming webhooks.
GET /
Displays a generated install page with an Add to Slack buttonGET /auth
Auth callback from the Add to Slack buttonPOST /
Executes slash command middlwares
The slack
object is an Express app so you can mount it on an existing app with app.use
or extend with regular web routes for doing things like authenticating 3rd party services.
import express from 'express'
import slack from 'slack-express'
// register a slash command handler
slack.slash('/rad', (payload, message)=> {
message({text:'rad indeed!'})
})
// create a fresh express app
let app = express()
// mount the slash commands on the /rad route
app.use('/rad', slack)
// add other routes and junk per norms
app.get('/', (req, res)=> res.end('index page'))
// as you do
app.listen(3777)
middleware
slack.slash
accepts any number of slash command middlewares. Symmetry with Express aside, the slack-express
middleware sub stack is a nice pattern for flow control, data transform pipelines and helps guide app modularization. Check it out:
import slack from 'slack-express'
function logger(payload, message, next) {
payload.custom = 'thing'
console.log(payload)
next()
}
function hello(payload, message) {
message({
text: 'hello world'
})
}
slack.slash('/hi', logger, hello)
slack.start()
the payload
The payload
parameter in the slack.slash
callback contains all the information from the slash command.
import slack from 'slack-express'
slack.slash('/console.log', (payload, message)=> {
// payload keys
let {ok, raw, message, account} = payload
// old school print styles debugger aw shiii
message({text:`${JSON.stringify(payload, null, 2)}`})
})
slack.start()
Use it to process the command and respond using Slack message formatted JSON message()
.
persistence
Slack slash commands are issued by real humans and you may wish to associate information with them. Databases are good for this! You can find and store data for each Slack account interacting with your app by using find
and save
. Currently only DynamoDB is supported but Redis will be an easy drop in.
api
slack
slash(cmd, (payload, message)=>) ... Register a slash command handler
start() ............................ Starts up the app
button() ........................... Add to Slack button for your app
find(params, (err, account)=>) ..... Find a saved Slack account
save(params, (err, account)=>) ..... Save a Slack account
local setup
You need to create an app with Slack for a SLACK_CLIENT_ID
and SLACK_CLIENT_SECRET
. Then you will need to create a .env
file with the following:
NODE_ENV=development
APP_NAME=dasherized-app-name-here
SLACK_CLIENT_ID=your-slack-client-id-here
SLACK_CLIENT_SECRET=your-slack-client-secret-here
SLACK_VERIFICATION_TOKEN=your-slash-command-verification-token-here
AWS_REGION=us-east-1
SECRET=your-secret-text-here
Don't forget to add .env
to your .gitignore
.