Blaxel Slack Agent

A powerful conversational agent that integrates seamlessly with Slack workspaces. This agent demonstrates advanced AI capabilities for building interactive Slack bots with tool integration, conversation management, and intelligent response generation.

📑 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📋 Prerequisites
• 💻 Installation
• 🔧 Slack Setup
• 🔧 Usage
  • Running Locally
  • Testing in slack
  • Deployment
• 📁 Project Structure
• ⚙️ Configuration
• ❓ Troubleshooting
• 👥 Contributing
• 🆘 Support
• 📄 License

✨ Features

• Slack Integration: Native Slack bot with real-time message handling
• Intelligent Conversations: Advanced AI-powered responses and context awareness
• Tool Integration: Support for external APIs, databases, and services
• Event Handling: Responds to mentions, direct messages, and slash commands
• Streaming Responses: Real-time message updates for better user experience
• Multi-workspace Support: Deploy across multiple Slack workspaces
• Secure Authentication: OAuth 2.0 and secure token management
• Easy Deployment: Seamless integration with Blaxel platform

🚀 Quick Start

For those who want to get up and running quickly:

# Clone the repository
git clone https://github.com/blaxel-templates/template-slack-chatbot.git

# Navigate to the project directory
cd template-slack-chatbot

# Install dependencies
uv sync

# Set up environment variables
cp .env.example .env
# Edit .env with your Slack credentials

# Start the server
bl serve --hotreload

📋 Prerequisites

• Python: 3.10 or later
• UV: An extremely fast Python package and project manager, written in Rust
• Slack Workspace: Admin access to create and configure Slack apps
• Blaxel Platform Setup: Complete Blaxel setup by following the quickstart guide
  • Blaxel CLI: Ensure you have the Blaxel CLI installed. If not, install it globally:

    curl -fsSL https://raw.githubusercontent.com/blaxel-templates/toolkit/main/install.sh | BINDIR=/usr/local/bin sudo -E sh

  • Blaxel login: Login to Blaxel platform

    bl login YOUR-WORKSPACE

💻 Installation

Clone the repository and install dependencies:

git clone https://github.com/blaxel-templates/template-slack-chatbot.git
cd template-slack-chatbot
uv sync

🔧 Slack Setup

Setup setup

🔧 Usage

Running the Server Locally

Start the development server with hot reloading:

bl serve --hotreload

Note: This command starts the server and enables hot reload so that changes to the source code are automatically reflected.

Testing in Slack

1. Invite your bot to a channel: /invite @your-bot-name
2. Mention your bot: @your-bot-name Hello!
3. Send a direct message to your bot
4. Use slash commands (if configured)

Deploying to Blaxel

When you are ready to deploy your application:

bl deploy

This command uses your code and the configuration files under the .blaxel directory to deploy your application.

📁 Project Structure

• src/main.py - Application entry point
• src/agent.py - Core Slack agent implementation
• src/slack_integration - Slack integration
• src/slack_router - Slack router including events handling
• src/slack_security - Slack check request is signed
• src/server/ - Server implementation and routing
  • middleware.py - Request/response middleware
• pyproject.toml - UV package manager configuration
• blaxel.toml - Blaxel deployment configuration
• .env.example - Environment variables template

⚙️ Configuration

Environment Variables

• SLACK_BOT_TOKEN - Your Slack bot token (required)
• SLACK_SIGNING_SECRET - Slack signing secret for request verification (required)

Blaxel Configuration

Edit blaxel.toml to customize:

• Model settings and preferences
• Function definitions and tools
• Deployment environment variables
• Resource allocation

❓ Troubleshooting

Common Issues

1. Slack Authentication Issues:

   • Verify your bot token starts with xoxb-
   • Check that your app is installed in the workspace
   • Ensure signing secret matches your Slack app settings

2. Permission Errors:

   • Verify bot has required OAuth scopes
   • Check that bot is invited to channels where it should respond
   • Ensure event subscriptions are properly configured

3. Event Handling Problems:

   • Confirm your Request URL is accessible and returns 200
   • Check that event subscriptions match your handler functions
   • Verify Slack can reach your webhook endpoint

4. Blaxel Platform Issues:

• Ensure you're logged in to your workspace: bl login MY-WORKSPACE
• Verify models are available: bl get models
• Check that functions exist: bl get functions

5. Bot Response Issues:

   • Check message formatting and Slack API limits
   • Verify conversation context and state management
   • Monitor rate limiting and API quotas

6. Deployment and Configuration:

   • Check environment variable configuration
   • Verify webhook URLs are publicly accessible
   • Review network connectivity and firewall settings

For more help, please submit an issue on GitHub.

👥 Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create a feature branch:

   git checkout -b feature/amazing-feature

3. Commit your changes:

   git commit -m 'Add amazing feature'

4. Push to the branch:

   git push origin feature/amazing-feature

5. Submit a Pull Request

Please make sure to update tests as appropriate and follow the code style of the project.

🆘 Support

If you need help with this template:

• Submit an issue for bug reports or feature requests
• Visit the Blaxel Documentation for platform guidance
• Check the Slack API Documentation for Slack-specific help
• Join our Discord Community for real-time assistance

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.