Skip to main content

🚀 Slack Work Arrangement Integration - Quick Start

What is this?​

This integration allows your team to track where they're working from (home, main office, or alternate office) by simply reacting to a daily Slack message with emojis. The system automatically tracks quotas (e.g., once per week for working from home) and provides an admin dashboard.

Quick Overview​

  1. Team Members: React to daily Slack message with 🏠, 🏢, or 🏛️
  2. System: Automatically records work location and tracks quota
  3. Admins: View dashboard at /work-arrangements to see who's working where

Setup (5 minutes)​

1. Create Slack App​

  1. Go to https://api.slack.com/apps → Create New App → From scratch
  2. Name: "Work Arrangement Tracker"
  3. Select your workspace

2. Add Permissions​

Go to OAuth & Permissions → Add Bot Token Scopes:

  • channels:history
  • reactions:read
  • users:read
  • chat:write

3. Enable Events​

Go to Event Subscriptions:

  • Enable Events: ON
  • Request URL: https://your-domain.com/api/slack/events
  • Subscribe to bot events: reaction_added

4. Install to Workspace​

  1. Go to Install App → Install to Workspace
  2. Copy the Bot User OAuth Token (starts with xoxb-)
  3. Go to Basic Information → Copy Signing Secret

5. Configure Environment​

Add to your .env.local:

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
SLACK_CHANNEL_ID=C01234ABCDE

6. Initialize Configuration​

Run this command (or use your API client):

curl -X POST https://your-domain.com/api/slack/config \
  -H "Content-Type: application/json" \
  -d '{
    "botToken": "xoxb-...",
    "signingSecret": "...",
    "channelId": "C01234ABCDE",
    "enabled": true
  }'

7. Map Engineers (Optional)​

Update engineer profiles to include Slack user IDs:

  • Find Slack user ID: Click profile → More → Copy member ID
  • Update in Firestore or via API

Daily Usage​

Morning Message​

Post this message in your configured channel:

Option 1: Manual posting (with auto-registration)

node scripts/post-daily-slack-message.js

Option 2: Post manually in Slack, then register: Post your message in Slack, then register its timestamp:

curl -X POST https://your-domain.com/api/slack/register-message \
  -H "Content-Type: application/json" \
  -d '{"messageTimestamp": "1637153524.000100"}'

Option 3: Automated via Cloud Function Deploy the Cloud Function and set up Cloud Scheduler (see documentation)

Message Template:

Good morning team! 🌅

Where are you working from today?
React with:
🏠 - Working from home
🏢 - Main office  
🏛️ - Alternate office

Important: The system only tracks reactions on registered daily messages. This prevents accidental tracking of reactions on other messages in the channel.

Team Reacts​

Team members simply react with the appropriate emoji. Done! ✅

View Dashboard​

Admins visit /work-arrangements to see:

  • Today's arrangements
  • Weekly summary
  • Quota status (who's used their home office quota)

Features​

✅ Automatic Tracking: No forms to fill out
✅ Quota Management: Track weekly home office usage (default: once per week)
✅ Team Dashboard: See who's where at a glance
✅ Weekly Reports: View quota status and trends
✅ Flexible Configuration: Customize emojis and quota limits

Configuration Options​

Edit via /api/slack/config:

{
  "emojiMapping": {
    "home": "🏠",
    "main_office": "🏢", 
    "alternate_office": "🏛️"
  },
  "quotaSettings": {
    "homeQuotaPerWeek": 1,
    "weekStartsOn": 1
  }
}

Firestore Collections Created​

  • work-arrangements: Individual daily arrangements
  • work-arrangement-quotas: Weekly quota summaries per engineer
  • system/slack-config: Slack integration configuration

API Endpoints​

  • POST /api/slack/events - Webhook (Slack posts here)
  • POST /api/slack/register-message - Register a daily message timestamp
  • GET /api/work-arrangements - Get arrangements
  • GET /api/work-arrangements/quotas - Get quota info
  • GET /api/slack/config - View configuration
  • POST /api/slack/config - Update configuration

Need Help?​

📖 Full setup guide: Slack work arrangement setup

Common issues:

  • Webhook not working? Check signing secret matches
  • Reactions not tracked? Add bot to channel
  • No engineer mapping? System still works, shows Slack username

Pro Tip: Set up a Cloud Function to automatically post the daily message at 9am. See the full documentation for details.