Skip to content

BLT Slack Bot Setup Guide

make sure to run this on your own server

Environment Variables

Required environment variables for the bot to function:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_ID_CLIENT=your-client-id
SLACK_WEBHOOK_URL=your-webhook-url

Slack App Configuration

  1. Create a new Slack App at https://api.slack.com/apps

  2. Under "OAuth & Permissions", add the following scopes: 

    channels:read
chat:write
groups:read
channels:join
im:write
users:read
team:read
commands

  3. Install the app to your workspace

  4. Copy the following credentials:

  5. Bot User OAuth Token → SLACK_BOT_TOKEN
  6. Signing Secret → SLACK_SIGNING_SECRET
  7. Client ID → SLACK_ID_CLIENT

Slash Commands

The bot currently supports the following commands: - /discover - View latest issues from repositories

Integration Setup

  1. Navigate to your organization's dashboard
  2. Click on "Add Slack Integration"
  3. Authorize the app for your workspace
  4. Configure the following settings:
  5. Default channel for notifications
  6. Daily update time (0-23 hour)
  7. Welcome message for new members

Features

Automatic Welcome Messages

  • Customizable welcome messages for new team members
  • Supports Slack markdown formatting
  • Sent via DM to new members

Daily Updates

  • Configurable daily updates about timelogs
  • Set specific hour for updates
  • Sent to designated channel

Repository Discovery

  • View latest issues from repositories
  • Interactive repository selection
  • Issue summaries with links

Command Handling

  • Slash command support
  • Interactive components
  • Error handling and user feedback

Activity Logging

  • Comprehensive activity tracking
  • Success/failure monitoring
  • Workspace-specific logging

Monitoring

Bot Activity Tracking

The bot's activity is logged in the SlackBotActivity model. You can monitor: - Success rates - Activity types - Workspace usage - Recent activities

Admin Interface

Access logs in Django admin under "Slack Bot Activity" with: - Filtering by activity type - Success/failure tracking - Workspace-specific views - Detailed error messages

Testing

Test files are available in website/test_slack.py for verifying: - Command handling - Event processing - Welcome message delivery - Integration functionality

Troubleshooting

Common issues and solutions:

  1. Bot Not Responding
  2. Verify environment variables are set correctly
  3. Check bot token permissions

  4. Ensure bot is invited to channels

  5. Welcome Messages Not Sending

  6. Verify bot has im:write permission
  7. Check workspace token is valid

  8. Ensure welcome message is configured

  9. Commands Not Working

  10. Verify slash command configuration
  11. Check signing secret is correct
  12. Ensure command URLs are accessible

Security Notes

  • Keep all tokens and secrets secure
  • Never commit environment variables to version control
  • Regularly rotate tokens and secrets
  • Monitor bot activity for unauthorized usage

Support

For additional support: - Check the BLT documentation - Review the Slack API documentation - Submit issues on the BLT GitHub repository