Phase 1: Hello Bot with Event Subscriptions

Overview

Phase 1 implements a basic Slack bot that responds to mentions with a "Hello!" message. This establishes the foundation for the Claude CS Bot by setting up:

• FastAPI web application with Slack event handling
• Slack signature verification for security
• URL verification challenge handling
• Background task processing to meet Slack's 3-second timeout
• Docker containerization
• Google Cloud Run deployment

Project Structure

.
├── main.py                 # FastAPI application with event handlers
├── config.py              # Configuration management with pydantic-settings
├── pyproject.toml         # Project dependencies and metadata
├── Dockerfile             # Multi-stage Docker build
├── .env.example           # Example environment variables
├── .env                   # Actual environment variables (gitignored)
├── deploy.sh              # Automated deployment script
├── DEPLOYMENT.md          # Detailed deployment guide
├── slack_manifest.json    # Slack app configuration manifest
├── tests/
│   ├── __init__.py
│   └── test_main.py       # Unit tests for all endpoints
└── README.md              # This file

Features Implemented

✅ 1. FastAPI Application Structure

• /health endpoint for health checks
• /slack/events endpoint for Slack event subscriptions
• Structured JSON logging
• Background task processing

✅ 2. Slack Signature Verification

• HMAC-SHA256 signature verification
• Timestamp validation (5-minute tolerance)
• Replay attack prevention
• Reference: https://api.slack.com/authentication/verifying-requests-from-slack

✅ 3. URL Verification Challenge

• Handles Slack's URL verification challenge
• Returns challenge parameter in JSON format
• Reference: https://api.slack.com/events/url_verification

✅ 4. App Mention Event Handling

• Responds to @slackbot mentions
• Posts response in thread (maintains conversation context)
• Ignores bot's own messages (prevents loops)
• Background processing to avoid 3-second timeout

✅ 5. Comprehensive Testing

• 9 unit tests covering all functionality
• Test coverage includes:
  • Health endpoint
  • Signature verification (valid/invalid/old timestamp)
  • URL verification challenge
  • App mention events
  • Bot message filtering
  • Invalid JSON handling

✅ 6. Docker Containerization

• Multi-stage build for smaller image size
• Uses uv package manager for fast dependency installation
• Non-root user for security
• Health check included
• Optimized for Cloud Run

✅ 7. Deployment Automation

• Automated deployment script (deploy.sh)
• Detailed deployment guide (DEPLOYMENT.md)
• Google Cloud Run configuration

Quick Start

Local Development

1. Install dependencies:

uv sync --extra dev

2. Set up environment variables:

cp .env.example .env
# Edit .env with your Slack credentials

3. Run tests:

uv run pytest tests/ -v

4. Run locally:

uv run uvicorn main:app --reload --port 8000

5. Expose with ngrok (for Slack webhook testing):

ngrok http 8000
# Update Slack Event Subscriptions URL with ngrok URL

Docker Testing

1. Build image:

docker build -t slack-claude-bot:latest .

2. Run container:

docker run --rm -p 8080:8080 --env-file .env slack-claude-bot:latest

3. Test health endpoint:

curl http://localhost:8080/health
# Expected: {"status":"ok"}

Deployment to Google Cloud Run

Option 1: Automated Script

./deploy.sh

The script will:

• Check authentication
• Enable required APIs
• Create Artifact Registry repository
• Build and push Docker image
• Deploy to Cloud Run
• Display service URL

Option 2: Manual Deployment

See DEPLOYMENT.md for detailed manual deployment instructions.

Slack App Setup

Method 1: Using Manifest (Recommended)

1. Go to https://api.slack.com/apps
2. Click "Create New App" → "From an app manifest"
3. Select your workspace
4. Copy contents from slack_manifest.json
5. Replace YOUR-CLOUD-RUN-URL with your actual Cloud Run URL
6. Create the app
7. Install to workspace
8. Copy Bot Token and Signing Secret

Method 2: Manual Configuration

1. Create new Slack app at https://api.slack.com/apps
2. Configure OAuth & Permissions:
   • Bot Token Scopes:
     • app_mentions:read
     • chat:write
     • channels:history
     • groups:history
     • im:history
     • mpim:history
3. Configure Event Subscriptions:
   • Enable Events: ON
   • Request URL: https://YOUR-CLOUD-RUN-URL/slack/events
   • Subscribe to bot events:
     • app_mention
4. Install App to Workspace
5. Copy Bot Token (starts with xoxb-) and Signing Secret

Testing the Bot

1. Invite bot to channel:

/invite @Claude CS Bot

2. Mention the bot:

@Claude CS Bot hello

3. Expected response:

Hello! I'm Claude CS Bot. I'm ready to help you!

Architecture

┌─────────────┐         ┌──────────────────┐         ┌──────────────┐
│             │  POST   │                  │  POST   │              │
│   Slack     │────────▶│  Cloud Run       │────────▶│  Slack Web   │
│   Events    │         │  (FastAPI App)   │         │  API         │
│             │◀────────│                  │         │              │
│             │  200 OK │                  │         │              │
└─────────────┘         └──────────────────┘         └──────────────┘
                              │
                              │ Background
                              ▼ Task
                        ┌─────────────┐
                        │   Process   │
                        │   Mention   │
                        └─────────────┘

Request Flow

1. Slack sends event → /slack/events endpoint
2. Signature verification → Validates request authenticity
3. Return 200 immediately → Meets 3-second timeout requirement
4. Background task → Processes mention and responds
5. Post message to Slack → Sends response in thread

Key Implementation Details

Slack Signature Verification

def verify_slack_signature(body: bytes, timestamp: str, signature: str) -> bool:
    # Check timestamp (5 minute tolerance)
    if abs(current_timestamp - int(timestamp)) > 60 * 5:
        return False

    # Compute HMAC-SHA256
    sig_basestring = f"v0:{timestamp}:{body.decode('utf-8')}"
    computed_signature = "v0=" + hmac.new(
        signing_secret.encode(),
        sig_basestring.encode(),
        hashlib.sha256,
    ).hexdigest()

    # Compare signatures
    return hmac.compare_digest(computed_signature, signature)

Background Task Processing

@app.post("/slack/events")
async def slack_events(
    request: Request,
    background_tasks: BackgroundTasks,
    ...
):
    # Verify signature
    # Parse event

    # Add to background tasks (non-blocking)
    background_tasks.add_task(process_app_mention, event_data)

    # Return immediately (within 3 seconds)
    return Response(status_code=200)

Thread Response

async def process_app_mention(event_data: dict):
    event = event_data["event"]
    channel = event["channel"]
    thread_ts = event.get("thread_ts") or event["ts"]  # Use existing thread or start new

    slack_client.chat_postMessage(
        channel=channel,
        thread_ts=thread_ts,  # Ensures response in thread
        text="Hello! I'm Claude CS Bot. I'm ready to help you!",
    )

Environment Variables

Required for Phase 1:

SLACK_BOT_TOKEN=xoxb-...           # Bot User OAuth Token
SLACK_SIGNING_SECRET=...           # Signing Secret for verification

Optional (for future phases):

ANTHROPIC_API_KEY=sk-ant-...       # Claude API key (Phase 2)
NOTION_API_KEY=secret_...          # Notion API key (Phase 3)
NOTION_DATABASE_ID=...             # Notion database ID (Phase 3)

Monitoring and Logs

View Cloud Run Logs

# Recent logs
gcloud run logs read slack-claude-bot --region us-central1 --limit 50

# Stream logs
gcloud run logs tail slack-claude-bot --region us-central1

Log Format

All logs use structured JSON format:

{
  "time": "2025-10-20 10:30:00",
  "level": "INFO",
  "message": {
    "action": "processing_mention",
    "channel": "C123456",
    "thread_ts": "1234567890.123456",
    "user": "U123456"
  }
}

Testing

Run All Tests

uv run pytest tests/ -v

Run with Coverage

uv run pytest tests/ --cov=. --cov-report=html
open htmlcov/index.html

Test Results

============================= test session starts ==============================
tests/test_main.py::TestHealthEndpoint::test_health_check PASSED         [ 11%]
tests/test_main.py::TestSlackSignatureVerification::test_verify_slack_signature_valid PASSED [ 22%]
tests/test_main.py::TestSlackSignatureVerification::test_verify_slack_signature_invalid PASSED [ 33%]
tests/test_main.py::TestSlackSignatureVerification::test_verify_slack_signature_old_timestamp PASSED [ 44%]
tests/test_main.py::TestURLVerification::test_url_verification_challenge PASSED [ 55%]
tests/test_main.py::TestURLVerification::test_url_verification_invalid_signature PASSED [ 66%]
tests/test_main.py::TestAppMentionEvent::test_app_mention_event PASSED   [ 77%]
tests/test_main.py::TestAppMentionEvent::test_app_mention_ignores_bot_messages PASSED [ 88%]
tests/test_main.py::TestAppMentionEvent::test_invalid_json_returns_400 PASSED [100%]

============================== 9 passed in 0.94s ===============================

Troubleshooting

Issue: URL Verification Challenge Fails

Symptoms: Slack shows "Your URL didn't respond with the value of the challenge parameter"

Solution:

1. Ensure service is deployed and accessible
2. Check logs for errors
3. Test endpoint manually:

curl -X POST https://YOUR-URL/slack/events \
  -H "Content-Type: application/json" \
  -d '{"type": "url_verification", "challenge": "test"}'
# Expected: {"challenge":"test"}

Issue: 403 Forbidden on Events

Symptoms: Events not being processed, 403 errors in logs

Solution:

1. Verify SLACK_SIGNING_SECRET is correct
2. Check Cloud Run environment variables
3. Ensure signature verification is not failing due to clock skew

Issue: Bot Not Responding

Symptoms: Bot doesn't reply to mentions

Solution:

1. Check bot is invited to channel: /invite @Claude CS Bot
2. Verify Event Subscriptions are configured
3. Check Cloud Run logs for errors
4. Ensure app_mention event is subscribed
5. Verify bot token has chat:write scope

Issue: Docker Build Fails

Symptoms: Error during docker build

Solution:

1. Ensure pyproject.toml has correct dependencies
2. Check Dockerfile syntax
3. Verify uv installation in container

Issue: Tests Fail

Symptoms: pytest shows failures

Solution:

1. Ensure .env file exists with test values
2. Check all dependencies installed: uv sync --extra dev
3. Verify Python version >= 3.11

Performance Metrics

Cold Start

• Average: 2-3 seconds
• Optimization: Set --min-instances 1 (costs more)

Response Time

• Health check: < 50ms
• URL verification: < 100ms
• Event processing: < 200ms (background task)

Resource Usage

• Memory: ~200MB (512MB allocated)
• CPU: Minimal during idle
• Cost: Within free tier for moderate use

Success Criteria

Phase 1 is complete when:

• ✅ All tests pass (9/9)
• ✅ Docker image builds successfully
• ✅ Health endpoint returns 200 OK
• ✅ URL verification challenge passes
• ✅ Bot responds to mentions with "Hello!" message
• ✅ Responses appear in thread
• ✅ Deployed to Cloud Run
• ✅ Slack Event Subscriptions verified

Next Steps

Once Phase 1 is working:

1. Verify in production:

   • URL verification passes
   • Bot responds to mentions
   • Logs show no errors

2. Prepare for Phase 2:

   • Get Anthropic API key
   • Review Claude Agent SDK documentation
   • Plan thread context management

3. Phase 2 Goals:

   • Replace static "Hello!" with Claude AI responses
   • Implement conversation history tracking
   • Add "Thinking..." → final response flow
   • Error handling for Claude API

References

• Slack Events API
• Slack Request Verification
• FastAPI Documentation
• Google Cloud Run
• uv Package Manager

Support

For issues or questions:

1. Check DEPLOYMENT.md for deployment issues
2. Review logs: gcloud run logs read slack-claude-bot
3. Verify Slack app configuration
4. Check environment variables are set correctly