Databricks Slackbot Template

A production-ready template for creating custom Slackbots that can be deployed on Databricks Apps using Databricks Asset Bundles (DABs) or run locally. This template provides a comprehensive foundation for building Slack integrations with Databricks workspace connectivity, LLM integration, and enterprise-grade monitoring.

🚀 Features

Production-Ready Architecture: Built with Flask, Gunicorn, and enterprise-grade patterns
Databricks Asset Bundles (DABs): Complete infrastructure-as-code deployment
LLM Integration: Built-in support for Databricks Foundation Model endpoints
Databricks Integration: Full workspace connectivity for data operations and AI workflows
Socket Mode: Uses WebSockets for secure enterprise connections
Thread Support: Maintains conversation context within Slack threads
REST API: Comprehensive API endpoints for health checks and direct messaging
Performance Monitoring: Built-in metrics, health checks, and system monitoring
Async Processing: Handles multiple users and channels concurrently with thread pools
Flexible Authentication: Support for OAuth2 service principals and personal access tokens
Auto-Deployment Script: Comprehensive deployment automation with validation and monitoring

📋 Prerequisites

Slack workspace with permissions to create apps
Databricks workspace with Databricks Apps enabled
Databricks CLI installed and configured
Python 3.8+ for local development
uv for fast dependency management (recommended)
(Optional) Foundation Model endpoint for LLM integration

🛠️ Getting Started

Step 1: Use This Template

Click "Use this template" to create a new repository from this template
Clone your new repository:

git clone https://github.com/your-username/your-slackbot-repo.git
cd your-slackbot-repo

Step 2: Set Up Your Slack App

Go to api.slack.com → Your Apps (top right corner)
Click Create New App → From a manifest → Select your Workspace
In the JSON tab, paste the following manifest and update the name:

{
    "display_information": {
        "name": "Your Bot Name"
    },
    "features": {
        "app_home": {
            "home_tab_enabled": true,
            "messages_tab_enabled": true,
            "messages_tab_read_only_enabled": false
        },
        "bot_user": {
            "display_name": "Your Bot Name",
            "always_online": false
        }
    },
    "oauth_config": {
        "scopes": {
            "bot": [
                "app_mentions:read",
                "channels:read",
                "chat:write",
                "files:read",
                "files:write",
                "im:history",
                "im:read",
                "im:write"
            ]
        }
    },
    "settings": {
        "event_subscriptions": {
            "bot_events": [
                "app_mention",
                "message.im"
            ]
        },
        "interactivity": {
            "is_enabled": true
        },
        "org_deploy_enabled": false,
        "socket_mode_enabled": true,
        "token_rotation_enabled": false
    }
}

Click Next → Create
In App Home, scroll down and enable "Allow users to send Slash commands and messages from the messages tab"
Under OAuth & Permissions → OAuth Tokens, install the app to your workspace
- Save the Bot User OAuth Token (starts with xoxb-) - this is your SLACK_BOT_TOKEN
Under Basic Information → App-Level Tokens:
- Click Generate Token and Scopes
- Name it (e.g., "Socket Mode Token")
- Add the connections:write scope
- Generate and save the token (starts with xapp-) - this is your SLACK_APP_TOKEN

💻 Local Development

1. Set Up Environment

Create a .env file from the template:

cp env.example .env

Edit .env with your tokens:

# Required
SLACK_APP_TOKEN=xapp-your-token-here
SLACK_BOT_TOKEN=xoxb-your-token-here

# Optional - for Databricks connectivity
DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_ACCESS_TOKEN=your-pat-token

2. Install Dependencies

# Using uv (recommended - faster dependency resolution)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv add -r slackbot/requirements.txt

# Alternative: Using traditional pip
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r slackbot/requirements.txt

3. Run the Bot

cd slackbot
python src/app.py

Your bot should now be running! Try sending it a direct message in Slack.

🚀 Deploying to Databricks Apps with DABs

1. Configure Databricks CLI

Ensure your Databricks CLI is configured for your workspace:

databricks auth login --host https://your-workspace.cloud.databricks.com

2. Configure Databricks Secrets

Store your Slack tokens securely in Databricks:

# In a Databricks notebook
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

scope_name = "slackbot"  # Must match SECRET_SCOPE in app.yaml
w.secrets.create_scope(scope=scope_name)

# Add your Slack tokens
w.secrets.put_secret(scope_name, "SLACK_APP_TOKEN", string_value="xapp-...")
w.secrets.put_secret(scope_name, "SLACK_BOT_TOKEN", string_value="xoxb-...")

3. Configure Your Deployment

Update configuration files for your environment:

Update slackbot/app.yaml:

env:
  - name: "SECRET_SCOPE"
    value: "slackbot"  # Your secret scope name
  - name: "LLM_ENDPOINT_NAME"
    value: "your-foundation-model-endpoint"  # Optional: your LLM endpoint
  - name: "DATABRICKS_HOST"
    value: "https://your-workspace.cloud.databricks.com"

Update databricks.yml (optional):

bundle:
  name: "your-slackbot-name"

variables:
  app_name:
    description: "Your Slackbot App Name"
    default: "your-slackbot-name"

4. Deploy Using the Automated Script

Use the provided deployment script for a complete automated deployment:

# Deploy to development environment
./deploy.sh dev

# Deploy to production environment
./deploy.sh prod

The deployment script will:

✅ Validate your bundle configuration
🏗️ Deploy infrastructure using Databricks Asset Bundles
🚀 Start your Slackbot app
🔍 Monitor the deployment status
📋 Provide next steps and useful commands

5. Manual Deployment (Alternative)

If you prefer manual control:

# Validate configuration
databricks bundle validate --target dev

# Deploy bundle
databricks bundle deploy --target dev

# Start the app
databricks bundle run slackbot_app --target dev

# Monitor app status
databricks apps get databricks-slackbot-dev --target dev

🏗️ Architecture Overview

This template follows enterprise-grade patterns with clear separation of concerns:

slackbot/
├── src/
│   ├── app.py              # Main Flask application entry point
│   ├── routes.py           # REST API endpoints and health checks
│   ├── slack_handlers.py   # Slack event and message handlers
│   ├── utils.py            # Core business logic and bot state management
│   ├── config.py           # Configuration management and validation
│   ├── databricks_client.py # Databricks workspace integration
│   └── llm_client.py       # LLM/Foundation Model integration
├── app.yaml                # Databricks Apps deployment configuration
└── requirements.txt        # Python dependencies

🎨 Customization

Core Message Processing

The main bot logic is in slackbot/src/utils.py. Find the process_user_message function:

def process_user_message(message_content: str, user_id: str, workspace_client: Optional[WorkspaceClient] = None) -> str:
    """
    Process a user message and return a response.
    Replace this with your custom logic.
    """
    # Your custom logic here
    response = f"🤖 Echo: {message_content}"

    # Add your own processing:
    # - Call LLM endpoints
    # - Query Databricks tables
    # - Run ML models
    # - Process data with Spark
    # - Integrate with external APIs

    return response

LLM Integration

The template includes built-in LLM support via llm_client.py. Configure your Foundation Model endpoint:

# In slackbot/app.yaml
env:
  - name: "LLM_ENDPOINT_NAME"
    value: "databricks-claude-3-7-sonnet"  # Your endpoint name

Use it in your message processing:

from .llm_client import LLMClient

def process_user_message(message_content: str, user_id: str, workspace_client: Optional[WorkspaceClient] = None) -> str:
    llm_client = LLMClient(workspace_client)
    response = llm_client.generate_response(message_content)
    return response

Databricks Integration

Leverage the full Databricks workspace capabilities:

if workspace_client:
    # Run SQL queries
    result = workspace_client.sql.execute("SELECT * FROM my_catalog.my_schema.my_table LIMIT 10")

    # Execute jobs
    job_run = workspace_client.jobs.run_now(job_id=123)

    # Access Unity Catalog
    tables = workspace_client.tables.list(catalog_name="my_catalog")

    # Manage ML models
    models = workspace_client.model_registry.list_models()

Custom Slack Commands

Add special commands in slack_handlers.py:

def handle_special_commands(message_content_stripped: str, say, message_ts: str, workspace_client=None) -> bool:
    if message_content_stripped in ['/analyze', 'analyze']:
        # Your custom analysis logic
        response = run_data_analysis(workspace_client)
        say(response, thread_ts=message_ts)
        return True

    if message_content_stripped.startswith('/query '):
        # Custom SQL query handler
        query = message_content_stripped[7:]  # Remove '/query '
        result = execute_safe_query(query, workspace_client)
        say(result, thread_ts=message_ts)
        return True

    return False

📚 API Endpoints

The bot provides comprehensive REST API endpoints for monitoring and direct interaction:

GET / - Health check with system metrics and status
GET /health - Simple health check endpoint
POST /api/chat - Send messages directly to the bot
GET /api/status - Detailed status and configuration information
GET /api/performance - Performance metrics and monitoring data

Example API usage:

# Health check
curl https://your-app-url.com/health

# Send message to bot
curl -X POST https://your-app-url.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello bot!", "user_id": "test_user"}'

# Get performance metrics
curl https://your-app-url.com/api/performance

🔧 Configuration

Key configuration options in slackbot/src/config.py:

MAX_WORKER_THREADS: Number of concurrent message processors
HEARTBEAT_INTERVAL: Monitoring heartbeat frequency
PERFORMANCE_UPDATE_INTERVAL: Metrics update frequency

📝 Built-in Commands

The template includes these built-in commands (customize in slack_handlers.py):

/help - Show help message and available commands
/status - Show system status and performance metrics

🔍 Monitoring and Observability

Databricks Apps Monitoring

Use these commands to monitor your deployed app:

# Check app status
databricks apps get databricks-slackbot-dev --target dev

# View real-time logs
databricks apps logs databricks-slackbot-dev --target dev

# List all apps
databricks apps list --target dev

# Start/stop app
databricks apps start databricks-slackbot-dev --target dev
databricks apps stop databricks-slackbot-dev --target dev

Health Checks

Monitor your app's health through the API endpoints:

# Quick health check
curl https://your-app-url.com/health

# Detailed status with metrics
curl https://your-app-url.com/api/status

# Performance metrics
curl https://your-app-url.com/api/performance

🐛 Troubleshooting

Deployment Issues

Bundle validation fails:
```
databricks bundle validate --target dev
```

App won't start:

# Check bundle deployment
databricks bundle deploy --target dev

# Check app logs
databricks apps logs databricks-slackbot-dev --target dev

Secret access issues:
- Verify secret scope exists: Check in Databricks workspace UI
- Ensure secrets are properly set: SECRET_SCOPE in app.yaml matches your scope

Bot Not Responding

Check Slack configuration:
- Verify tokens in Databricks secrets or .env file
- Ensure SLACK_APP_TOKEN starts with xapp-
- Ensure SLACK_BOT_TOKEN starts with xoxb-
- Confirm Socket Mode is enabled in Slack app settings

Check app connectivity:

# Test health endpoint
curl https://your-app-url.com/health

# Check app logs for connection errors
databricks apps logs databricks-slackbot-dev --target dev

Slack app configuration:
- Bot must be installed in your workspace
- For channels, bot must be added to the channel
- Verify event subscriptions are enabled
- Check OAuth scopes match the template requirements

Performance Issues

Check system metrics:

curl https://your-app-url.com/api/performance

Review configuration in config.py:
- Adjust MAX_WORKER_THREADS for concurrency
- Modify timeout settings if needed

Monitor resource usage:

# Check app resource consumption
databricks apps get databricks-slackbot-dev --target dev

📄 License

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

📁 Project Structure

databricks-slackbot-template/
├── databricks.yml           # Databricks Asset Bundle configuration
├── deploy.sh               # Automated deployment script
├── app.yaml.example        # Example app configuration
├── env.example             # Example environment variables
├── slackbot/               # Main application directory
│   ├── src/
│   │   ├── app.py          # Flask application entry point
│   │   ├── routes.py       # REST API endpoints
│   │   ├── slack_handlers.py # Slack event handling
│   │   ├── utils.py        # Core business logic
│   │   ├── config.py       # Configuration management
│   │   ├── databricks_client.py # Databricks integration
│   │   └── llm_client.py   # LLM integration
│   ├── app.yaml            # Databricks Apps configuration
│   └── requirements.txt    # Python dependencies
└── README.md               # This file

🚀 Quick Start Checklist

Use this template to create your repository
Set up Slack app with provided manifest
Configure Databricks CLI authentication
Create Databricks secret scope with Slack tokens
Update slackbot/app.yaml with your configuration
Run ./deploy.sh dev to deploy
Test bot functionality in Slack
Customize message processing logic in utils.py

🤝 Contributing

Contributions are welcome! This template aims to provide the best foundation for Databricks Slackbot development.

Fork the repository
Create a feature branch
Make your changes
Test with both local and Databricks Apps deployment
Submit a pull request

📧 Support

📖 Check the troubleshooting section above
🔍 Review Databricks Apps documentation
🐛 Open an issue on GitHub for bugs or feature requests
💬 Ask questions in the GitHub Discussions

🏷️ Related Resources

This is a production-ready template. Customize it to fit your specific use cases and requirements. Built with ❤️ for the Databricks community.

Name		Name	Last commit message	Last commit date
slackbot		slackbot
.DS_Store		.DS_Store
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
app.yaml.example		app.yaml.example
databricks.yml		databricks.yml
deploy.sh		deploy.sh
env.example		env.example

Latest commit

History

Folders and files

Repository files navigation