Slack Appreciation Bot

A Slack bot for peer-to-peer appreciation aligned with company values. This bot allows team members to recognize each other using a simple syntax, with point awarding, daily limits, a leaderboard, and redeemable rewards.

Features

• Recognition via "@user +++ for ... #value" syntax (multi-user and usergroup aware)
• Point awards based on + count with daily budget enforcement
• Company values tagging with #value and a #general fallback
• Celebration GIFs for recognitions (PG-rated, fixed-height to avoid scrolling)
• App Home experience: stats, leaderboard, goodies store, admin settings
• Admin configuration commands for limits, values, labels, rewards, and GIF controls
• Reward redemption flow with modal or slash command
• Postgres-backed storage with optional token encryption at rest
• Zero-cost hosting compatibility

Getting Started

Prerequisites

• Node.js (v14 or newer)
• npm or yarn
• A Slack workspace with admin rights
• Docker (optional, for local Postgres)

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/slack-appreciation-bot.git
   cd slack-appreciation-bot

2. Install dependencies:

   npm install

3. Create a .env file in the root directory with your Slack credentials:

   SLACK_CLIENT_ID=your-client-id
   SLACK_CLIENT_SECRET=your-client-secret
   SLACK_STATE_SECRET=your-random-state-secret
   SLACK_SIGNING_SECRET=your-signing-secret
   SLACK_SCOPES=chat:write,commands,users:read,usergroups:read,channels:read,im:read,mpim:read,groups:read,channels:history,groups:history,im:history,mpim:history
   GIPHY_API_KEY=your-giphy-api-key
   DATABASE_URL=postgres://appreciation:appreciation@localhost:5432/appreciation
   DATABASE_SSL=false
   SLACK_INSTALL_ENCRYPTION_KEY=your-random-32-byte-secret
   PORT=3000
   

   Token-based (single workspace) setup is also supported. If you prefer to skip OAuth, set:

   SLACK_BOT_TOKEN=xoxb-your-bot-token
   SLACK_SIGNING_SECRET=your-signing-secret
   GIPHY_API_KEY=your-giphy-api-key
   DATABASE_URL=postgres://appreciation:appreciation@localhost:5432/appreciation
   DATABASE_SSL=false
   PORT=3000
   

4. Build the TypeScript code:

   npm run build

5. Start the bot:

   npm start

Creating a Slack App

1. Go to https://api.slack.com/apps and click "Create New App"
2. Choose "From scratch" and provide a name for your app
3. Under "Basic Information", note your Signing Secret
4. Under "Socket Mode", enable it and create an App-Level Token with the connections:write scope
5. Under "OAuth & Permissions":
   • Add the following Bot Token Scopes:
     • app_mentions:read
     • channels:history
     • channels:read
     • chat:write
     • commands
     • groups:history
     • im:history
     • users:read
     • reactions:write
   • Install the app to your workspace
   • Note your Bot User OAuth Token
6. Under "Event Subscriptions":
   • Enable events
   • Subscribe to bot events:
     • app_home_opened
     • message.channels
     • message.groups
     • message.im
7. Under "Slash Commands":
   • Create the following commands:
     • /points
     • /redeem
8. Under "App Home":
   • Enable the Home Tab

Usage

Note: The bot only receives messages in channels it has been invited to. Use /invite @your-bot-name in any channel where you want recognitions to work.

Updated Recognition Syntax

To recognize a team member, use the following syntax in any channel where the bot is present:

@username ++ helped me debug an issue #innovation

This awards the user 2 points for the "innovation" value. The number of + symbols determines the points awarded.

You can also recognize multiple users or groups in a single message:

@username1 @username2 +++ for great teamwork #teamwork
@developers ++ let's go #teamwork

• The first example awards 3 points to both @username1 and @username2 for the "teamwork" value.
• The second example awards 2 points to all members of the @developers group for the "teamwork" value.

Commands

Admin Commands

• /points config daily_limit <n> - Set the daily point limit
• /points config add_value <value> - Add a company value
• /points config remove_value <value> - Remove a company value
• /points config label <label> - Set a custom name for points (e.g. "kutanacoins")
• /points config gif_enabled on|off - Enable or disable celebration GIFs
• /points config gif_min_points <n> - Set the minimum points required for a GIF
• /points reward add "Reward Name" <cost> - Add a redeemable reward
• /points reward remove "Reward Name" - Remove a reward
• /points reset @user - Reset a user's points to 0
• /points reset all - Reset all users' points to 0

User Commands

• /redeem "Reward Name" - Redeem a reward
• /redeem (without arguments) - Open the redemption modal

App Home

The App Home shows:

• A section selector dropdown with the following options:
  • Home: Your stats, points by value, how to recognize, and how to redeem.
  • Recognition Leaderboard: Top recognized team members this month.
  • Goodies store: Browse and redeem configured rewards via buttons.
  • Settings (admins only): View and modify app configuration directly (daily limit, company values, rewards catalog, GIF controls, reset points) through interactive controls.

When in Settings, admins see current configuration values and buttons to set daily limits, toggle GIFs, set GIF minimum points, add/remove values and rewards, or reset individual/all user points directly from the UI.

Data Storage

Data is stored in Postgres. For local development you can run a Postgres container:

npm run db:up

To stop it:

npm run db:down

For hosted databases that require SSL, set DATABASE_SSL=true. If you set SLACK_INSTALL_ENCRYPTION_KEY, bot tokens will be encrypted at rest before being stored.

Hosting

This bot can be hosted on various free tier platforms:

• Heroku Free Dyno
• Glitch.com
• Replit
• Railway.app free tier

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Write tests for your changes
5. Run the test suite to ensure functionality (npm test)
6. Push to the branch (git push origin feature/my-new-feature)
7. Create a new Pull Request

Testing

Run tests using:

npm test

License

This project is licensed under the MIT License - see the LICENSE file for details.