Slack Follow-up Task Bot

A Laravel-based Slack bot that helps executives assign, track, and follow up on tasks with automated reminders and comprehensive task management features.

🚀 Features

Task Creation & Assignment

• Slash Command: Use /follow-up to create new tasks
• Message Shortcuts: Create tasks directly from Slack messages using the "Create Follow-up Task" shortcut
• Rich Task Details: Set title, description, assignee, due date, priority, and follow-up frequency
• Custom Messages: Add custom messages with @mentions for due date notifications
• Thread Support: Tasks created from messages post updates in the original thread

Automated Follow-ups

• Smart Reminders: Automatic follow-up messages based on configurable intervals (1, 2, 3, or 7 days)
• Interactive Buttons: Assignees can respond with ✅ Completed, 🔄 Still Working, ⚠️ Need Help, or 📅 Request Extension
• Executive Notifications: Real-time updates to task assigners about progress, completion, or help requests

Extension Management

• Extension Requests: Employees can request deadline extensions with reasons
• Executive Approval: Automated approval workflow with approve/deny buttons
• Extension History: Track multiple extension requests per task

Task Monitoring

• Dashboard Command: Use /task-status to view all active assigned tasks
• Overdue Alerts: Automatic notifications for overdue tasks
• Priority Levels: High (🔴), Medium (🟡), Low (🟢) priority indicators

🛠️ Technology Stack

• Backend: Laravel 11+ (PHP 8.3+)
• Database: PostgreSQL 16+ (MySQL also supported)
• Containerization: Docker with Docker Compose
• Database Management: Adminer (web-based database management)
• Web Server: Nginx (in Docker)
• Process Manager: Supervisor (for background tasks)
• Slack Integration: JoliCode Slack PHP API
• Queue System: Laravel Queues for scheduled tasks
• Security: Slack request signature verification

📋 Requirements

For Docker Setup (Recommended)

• Docker and Docker Compose
• Slack App with appropriate permissions

For Manual Setup

• PHP 8.3 or higher
• Laravel 11+
• PostgreSQL 16+ (or MySQL 8.0+)
• Composer
• Slack App with appropriate permissions

⚡ Installation

🐳 Docker Setup (Recommended)

1. Clone and Setup Project

git clone <repository-url>
cd slack-followup-bot
cp .env.example .env

2. Configure Environment Variables

The .env.example file comes pre-configured for Docker. Key variables:

# Application
APP_NAME="Slack Follow-up Bot"
APP_ENV=local
APP_DEBUG=true

# Ports
WEBSERVER_PORT=8081        # Laravel app will be available at http://localhost:8081
ADMINER_PORT=8083          # Adminer will be available at http://localhost:8083

# Database (PostgreSQL)
DB_CONNECTION=pgsql
POSTGRES_DB=follow_up
POSTGRES_USER=root
POSTGRES_PASSWORD=password
DB_PORT=5432

# Slack Configuration (add your actual values)
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_SIGNING_SECRET=your-signing-secret-here
SLACK_CLIENT_ID=your-client-id-here
SLACK_CLIENT_SECRET=your-client-secret-here

3. Build and Start Services

# Build and start all services in development mode
docker-compose up --build

# Or run in detached mode (background)
docker-compose up -d --build

This will start:

• Laravel App: Available at http://localhost:8081
• PostgreSQL Database: Running on port 5432
• Adminer: Database management interface at http://localhost:8083

4. Initialize Database

Once the containers are running, set up the database:

# Generate application key (if not done already)
docker-compose exec app php artisan key:generate

# Run database migrations
docker-compose exec app php artisan migrate

# Optional: Seed the database
docker-compose exec app php artisan db:seed

5. Accessing Services

Laravel Application

• URL: http://localhost:8081
• Health Check: http://localhost:8081/api/slack/health

Adminer (Database Management)

• URL: http://localhost:8083
• System: PostgreSQL
• Server: postgres
• Username: root (or value from POSTGRES_USER)
• Password: password (or value from POSTGRES_PASSWORD)
• Database: follow_up (or value from POSTGRES_DB)

6. Development Commands

# View logs
docker-compose logs -f app
docker-compose logs -f postgres

# Access Laravel container shell
docker-compose exec app bash

# Run Laravel commands
docker-compose exec app php artisan migrate
docker-compose exec app php artisan tinker
docker-compose exec app php artisan schedule:work

# Restart services
docker-compose restart

# Stop all services
docker-compose down

# Remove all containers and volumes (clean slate)
docker-compose down -v

7. Using Cloudflared Tunnel with Docker

To expose your Dockerized application for Slack webhook testing:

# Make sure your Docker containers are running
docker-compose up -d

# Start cloudflared tunnel
cloudflared tunnel --url http://localhost:8081

8. Production Deployment

For production deployment, use the production target:

# Set production environment
export BUILD_TARGET=production
export APP_ENV=production

# Build and deploy
docker-compose up --build -d

---

🛠️ Manual Installation (Alternative)

1. Clone and Setup Laravel Project

git clone <repository-url>
cd slack-followup-bot
composer install
cp .env.example .env
php artisan key:generate

2. Database Configuration

# Configure your .env file
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=slack_followup_bot
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Run migrations
php artisan migrate

3. Install Slack PHP API

composer require jolicode/slack-php-api

4. Slack App Configuration

Create a Slack App at https://api.slack.com/apps with these configurations:

Required Bot Token Scopes:

channels:read
chat:write
commands
groups:read
im:read
mpim:read
users:read

Slash Commands:

• /follow-up - Description: "Create a new task follow-up"
• /task-status - Description: "View your active assigned tasks"

Event Subscriptions:

• app_mention - When the bot is mentioned

Interactive Components:

• Enable Interactive Components for button interactions and modals

Message Shortcuts:

• Callback ID: create_followup_from_message
• Name: "Create Follow-up Task"
• Description: "Create a follow-up task from this message"

5. Environment Configuration

Add to your .env file:

# Slack Configuration
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_VERIFY_REQUESTS=true

6. Configure Services

In config/services.php:

'follow-up-slack' => [
    'bot_token' => env('SLACK_BOT_TOKEN'),
    'signing_secret' => env('SLACK_SIGNING_SECRET'),
    'verify_requests' => env('SLACK_VERIFY_REQUESTS', true),
],

7. Setup Scheduled Commands

Add to your server's crontab:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Or run the scheduler manually for development:

php artisan schedule:work

🎯 Usage

Creating Tasks

Method 1: Slash Command

1. Type /follow-up in any Slack channel
2. Fill out the modal with task details:
   • Assignee: Select team member
   • Task Title: Brief task description
   • Task Description: Detailed requirements
   • Due Date: Task deadline
   • Follow-up Frequency: How often to send reminders
   • Priority: High, Medium, or Low
   • Custom Message: Optional message with @mentions for due date

Method 2: Message Shortcut

1. Hover over any message
2. Click the "More actions" (⋯) menu
3. Select "Create Follow-up Task"
4. Fill out the modal (task will be linked to original message)

Managing Tasks

For Assignees:

• Receive automated follow-up messages with interactive buttons
• Click ✅ Completed when task is done
• Click 🔄 Still Working to reschedule follow-up
• Click ⚠️ Need Help to request assistance
• Click 📅 Request Extension to extend deadline

For Executives:

• Receive real-time notifications about task progress
• Approve or deny extension requests
• Use /task-status to view dashboard of all assigned tasks
• Get alerts about overdue tasks

📁 Project Structure

app/
├── Console/Commands/
│   └── ProcessTaskFollowupsCommand.php    # Automated task processing
├── Enums/                                 # Slack interaction enums
│   ├── SlackActionIdEnum.php
│   ├── SlackBlockIdEnum.php
│   ├── SlackCallbackIdEnum.php
│   ├── TaskStatusEnum.php
│   ├── TaskPriorityEnum.php
│   └── ExtensionStatusEnum.php
├── Http/
│   ├── Controllers/Api/V1/
│   │   └── SlackController.php            # Main Slack interaction handler
│   └── Middleware/
│       └── VerifySlackRequestMiddleware.php # Security middleware
├── Models/
│   ├── TaskFollowup.php                   # Main task model
│   └── TaskExtensionRequest.php           # Extension request model
└── Services/
    └── SlackService.php                   # Slack API integration service

🗄️ Database Schema

task_followups

• Task details and metadata
• Slack user and channel information
• Follow-up scheduling
• Custom messages and mentions
• Thread management

task_extension_requests

• Extension request details
• Approval workflow tracking
• Decision history

🔧 Configuration

Follow-up Intervals

Configure available intervals in SlackService::getEnhancedModalBlocks():

• Every 3 days
• Weekly (7 days)

Task Priorities

• High (🔴)
• Medium (🟡) - Default
• Low (🟢)

Task Statuses

• Pending
• In Progress
• Completed
• Need Help
• Extension Requested
• Cancelled

🚨 Security

• Request Verification: All Slack requests are verified using signing secrets
• Middleware Protection: Custom middleware validates all incoming requests
• Environment-based: Verification can be disabled in local development

🔍 Monitoring & Logs

The bot logs all activities for debugging and monitoring:

• Task creation and updates
• Slack API interactions
• Extension requests and approvals
• Follow-up message delivery
• Error handling and exceptions

🐛 Troubleshooting

Common Issues

1. Modals not opening: Check trigger_id validity and bot permissions
2. Messages not sending: Verify bot token and channel permissions
3. Signature verification failing: Ensure signing secret is correct
4. Scheduled tasks not running: Verify cron job setup and Laravel scheduler

Debug Mode

For local development, disable request verification:

SLACK_VERIFY_REQUESTS=false

🌐 Development Setup

Docker Setup (Recommended)

The application is designed to run with Docker and includes PostgreSQL and Adminer:

# Start all services
docker-compose up -d --build

# The application will be available at:
# - Laravel App: http://localhost:8081
# - Adminer (Database UI): http://localhost:8083

Manual Setup (Alternative)

If you prefer to run without Docker:

# Start the Laravel development server
php artisan serve --host=0.0.0.0 --port=8081

Exposing Local Development with Cloudflared Tunnel

For testing Slack integrations during development, you can use Cloudflared tunnel to expose your local server:

# For Docker setup
docker-compose up -d
cloudflared tunnel --url http://localhost:8081

# For manual setup
php artisan serve --host=0.0.0.0 --port=8081
cloudflared tunnel --url http://localhost:8081

This will provide a public HTTPS URL that you can use in your Slack app configuration for:

• Request URL for slash commands
• Event Request URL for event subscriptions
• Interactivity Request URL for interactive components

Note: Make sure your application is running on port 8081 before starting the tunnel.

📝 API Endpoints

GET  /api/slack/health                    # Health check
POST /api/v1/slack/events                 # Slack events webhook
POST /api/v1/slack/commands/follow-up     # Follow-up slash command
POST /api/v1/slack/commands/task-status   # Task status slash command
POST /api/v1/slack/interactive            # Interactive components (buttons, modals)