Slack Karma Bot

A lean no-database Slack bot app that allows a user to give karma points to other users.

The bot can process karma commands in any public or private channel that it's added to.

How it works

All the karma scores for the users in the Slack workspace is stored in a Slack message.

It's recommended that you create a private channel in your Slack workspace to store the karma scores and only add the karma bot and admins of the karma bot to the channel.

App Initialization

Create a node app that initializes the Slack Karma Bot app like such.

import { App } from "slack-karma-bot"

const app = new App({
   token: process.env.SLACK_BOT_TOKEN,
   signingSecret: process.env.SLACK_SIGNING_SECRET,
   scoreMapStoreChannelId: process.env.SCORE_MAP_STORE_CHANNEL_ID,
   scoreMapStoreMessageTs: process.env.SCORE_MAP_STORE_MESSAGE_TS
})

You need both the token and signingSecret before the bot can do anything.

What the environmental variables mean:

• SLACK_BOT_TOKEN is the bot token you can retrieve from the OAuth & Permissions tab https://api.slack.com/apps/{APP_ID}/oauth
• SLACK_SIGNING_SECRET is the signing secret that allows the Karma Bot App to verify that incoming requests are coming from Slack. You can retrieve from the App Credentials section of https://api.slack.com/apps/{APP_ID}
• SCORE_MAP_STORE_CHANNEL_ID is the private channel where you are storing the karma scores. To get the channel id, right click the channel and select "View channel details".
• SCORE_MAP_STORE_MESSAGE_TS is the ts value of the message where the karma score map is stored. The ts value is essentially the ID of the message. To get the ts value, add the karma bot to the channel, then mention it with "init" message. The karma bot will initialize the empty score object in a new message, then provide the ts value of the first new message in a second new message.

Running the App

The bot app wraps bolt so calling the start method will call the start method in bolt.

(async () => {
  const port = Number(process.env.PORT) || 3000
  console.log(`Starting app on port ${port}`)

  await app.start(port)

  console.log("⚡️ Bolt app is running!")
})()

Datastore Initialization

After you have started the bot, you need to use the bot to initialize the datastore where you want the karma points to be kept. This is a one-time setup.

1. Invite the karma bot to the private channel.

2. Initialize the data store

   1. Option 1: initialize with empty data:

      @<bot_name> init

   2. Option 2: initialize with existing data:

      @<bot_name> init <existing_data>

   existing_data will be a stringified JSON object that contains the karma score map. The format of the JSON object is:

   { "<user_id_1>": 1, "<user_id_2>": 1, "<user_id_3>": 10 }

3. Retrieve the ts value posted by the bot.

4. Add the ts value to the SCORE_MAP_STORE_MESSAGE_TS environment variable and restart your app.

Karma Bot Commands

Give karma points to a user

@<user_name> ++

You can add any text after the ++ to give context for why you are giving the karma point.

Initialize the store

@<bot_name> init

@<bot_name> init { "<user_id_1>": 1, "<user_id_2>": 1, "<user_id_3>": 10 }

Develop

You can try out the Slack Karma Bot app in development mode by running the following command which spins up the node server in example/index.ts

Clone the repo, then install all the dependencies.

nvm use
yarn

yarn dev

HMR is supported but every time you make a change to the .env file, you will need to restart the server for the change to take effect.

The Slack app server start on localhost:3000. You can use ngrok to proxy your local server to the internet via a public URL.

brew install ngrok/ngrok/ngrok
ngrok http 3000

After running the command, the ngrok console will display the public URL that Slack can use to access your local server. Go to https://api.slack.com/apps/{APP_ID}/event-subscriptions and make the Request URL {ngrok-url}/slack/events

Resources

• conversations-api for how to get the channel ID.
• retrieving individual messages