← back to Daily Reporting

SLACK-SETUP-GUIDE.md

473 lines

# Slack Integration Setup Guide

Complete guide for setting up Slack integration with DW-Agents Daily Reporting System.

## Step-by-Step Setup

### 1. Create Slack App

1. Go to https://api.slack.com/apps
2. Click **"Create New App"**
3. Select **"From scratch"**
4. Enter app name: **DW-Agents Reporter**
5. Select your workspace
6. Click **"Create App"**

### 2. Enable Incoming Webhooks

1. In your app settings, click **"Incoming Webhooks"** (left sidebar)
2. Toggle **"Activate Incoming Webhooks"** to ON
3. Scroll down and click **"Add New Webhook to Workspace"**
4. Select the channel: **#morning-report** (create it first if needed)
5. Click **"Allow"**

You'll see a webhook URL like:
```
https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX
```

**Important**: Keep this URL secure! It's like a password for your Slack channel.

### 3. Create #morning-report Channel

If you haven't created the channel yet:

1. In Slack, click the **+** next to "Channels"
2. Name it: **morning-report**
3. Description: `Daily automated reports from DW-Agents system`
4. Set it to **Public** or **Private** (your choice)
5. Click **"Create"**

### 4. Invite Team Members

In the #morning-report channel:

```
/invite @username
```

Or click the channel name > "Members" > "Add people"

### 5. Configure Environment Variables

#### Option A: Add to ~/.bashrc (Persistent)

```bash
# Edit bashrc
nano ~/.bashrc

# Add these lines at the end:
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
export SLACK_CHANNEL="#morning-report"
export REPORTS_DIR="/root/DW-Agents/reports"

# Save and reload
source ~/.bashrc
```

#### Option B: Add to Crontab (Cron-specific)

```bash
crontab -e

# Add these lines at the top:
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
SLACK_CHANNEL=#morning-report
REPORTS_DIR=/root/DW-Agents/reports
```

### 6. Test Connection

```bash
cd /root/.claude/skills/daily-reporting
tsx daily-report-runner.ts test
```

You should see:
```
🧪 Testing Slack webhook connection...
✅ Slack connection successful!
   Channel: #morning-report
   Check your Slack channel for a test message.
```

## Webhook URL Format

The webhook URL should look like this:

```
https://hooks.slack.com/services/T{WORKSPACE_ID}/B{CHANNEL_ID}/{TOKEN}
```

Example:
```
https://hooks.slack.com/services/T012AB3C4D5/B678EF9G0H1/abcdefghijklmnopqrstuvwx1234567
```

### URL Components:
- **T012AB3C4D5**: Your workspace ID
- **B678EF9G0H1**: The channel/webhook ID
- **abcdef...**: Secret token (32 characters)

## Channel Configuration

### Recommended Channel Settings

1. **Name**: `#morning-report`
2. **Topic**: `📊 Daily automated reports - Morning at 6:00 AM | EOD at 5:00 PM`
3. **Description**:
   ```
   Automated daily reports from DW-Agents hierarchy system.

   Report Types:
   - ☀️ Morning Standup (6:00 AM)
   - 🌙 End-of-Day Summary (5:00 PM)

   Dashboard: http://45.61.58.125:9893
   ```

4. **Notifications**:
   - Set to **All messages** for critical updates
   - Or **Mentions only** to reduce noise

### Channel Permissions

**Public Channel** (Recommended):
- ✅ Anyone in workspace can join
- ✅ Searchable message history
- ✅ Easy for new team members

**Private Channel**:
- ⚠️ Invite-only access
- ⚠️ More secure for sensitive data
- ⚠️ Requires manual invitation

## Message Formatting

### What You'll Receive

#### Morning Report (6:00 AM)
```
☀️ MORNING STANDUP REPORT
Friday, November 9, 2025
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 EXECUTIVE SUMMARY
...

🏢 DEPARTMENT REPORTS
...

🚨 ISSUES REQUIRING ATTENTION
...

✅ ACTION ITEMS
...

💬 Q&A READINESS STATUS
...
```

#### EOD Report (5:00 PM)
Same format, with full day's statistics.

### Alert Mentions

If there are **critical issues**, the bot will mention the channel:

```
<!channel> Attention Required - Critical issues detected!

☀️ MORNING STANDUP REPORT
...
```

You'll receive a notification from Slack.

## Customization

### Change Report Times

Edit the cron schedule:

```bash
crontab -e
```

**Current schedule**:
```
0 6 * * * ...    # 6:00 AM
0 17 * * * ...   # 5:00 PM
```

**Custom times**:
```
0 7 * * * ...    # 7:00 AM
0 18 * * * ...   # 6:00 PM
30 8 * * * ...   # 8:30 AM
```

### Change Channel

```bash
export SLACK_CHANNEL="#operations"
```

Update in crontab:
```bash
crontab -e
# Change: SLACK_CHANNEL=#operations
```

### Disable @channel Mentions

Edit `/root/.claude/skills/daily-reporting/daily-report-runner.ts`:

```typescript
const slackConfig = {
  webhookUrl: SLACK_WEBHOOK_URL,
  channel: SLACK_CHANNEL,
  username: 'DW-Agents Reporter',
  iconEmoji: reportType === 'morning' ? ':sunrise:' : ':city_sunset:',
  mentionChannelOnIssues: false  // Change to false
};
```

### Custom Bot Name and Icon

In `slack-notifier.ts`:

```typescript
const payload = {
  username: 'Your Bot Name',           // Custom name
  icon_emoji: ':robot_face:',          // Custom emoji
  // Or use custom image:
  icon_url: 'https://example.com/bot-icon.png'
};
```

## Multiple Channels

To send reports to multiple channels, create separate webhooks:

### 1. Create Additional Webhooks

Repeat Step 2 above for each channel:
- #executive-reports
- #it-operations
- #department-heads

### 2. Configure Multiple Webhooks

```bash
export SLACK_WEBHOOK_EXEC="https://hooks.slack.com/services/T.../B.../exec..."
export SLACK_WEBHOOK_OPS="https://hooks.slack.com/services/T.../B.../ops..."
```

### 3. Modify Script

Edit `daily-report-runner.ts` to send to multiple webhooks:

```typescript
const webhooks = [
  { url: process.env.SLACK_WEBHOOK_URL, channel: '#morning-report' },
  { url: process.env.SLACK_WEBHOOK_EXEC, channel: '#executive-reports' },
  { url: process.env.SLACK_WEBHOOK_OPS, channel: '#it-operations' }
];

for (const webhook of webhooks) {
  await sendToSlack(report, {
    webhookUrl: webhook.url,
    channel: webhook.channel,
    ...
  });
}
```

## Troubleshooting

### "Invalid webhook URL"

**Problem**: The webhook URL is incorrect or expired.

**Solution**:
1. Go to https://api.slack.com/apps
2. Select your app
3. Click "Incoming Webhooks"
4. Verify the webhook URL
5. If deleted, create a new webhook
6. Update environment variable

### "Channel not found"

**Problem**: The channel doesn't exist or webhook wasn't added to it.

**Solution**:
1. Verify channel exists: `/join #morning-report`
2. Recreate the webhook for the correct channel
3. Update webhook URL in environment

### "No test message received"

**Problem**: Slack webhook might be inactive or network issues.

**Solution**:
```bash
# Test with curl
curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Test from command line"}' \
  $SLACK_WEBHOOK_URL

# Check network connectivity
ping hooks.slack.com

# Verify firewall allows outbound HTTPS
curl -I https://hooks.slack.com
```

### "Messages not formatted correctly"

**Problem**: Slack markdown rendering issues.

**Solution**:
- Slack uses mrkdwn, not full markdown
- Don't use HTML tags
- Use supported formatting:
  - `*bold*` → **bold**
  - `_italic_` → _italic_
  - `~strikethrough~` → ~~strikethrough~~
  - `` `code` `` → `code`
  - `>` for quotes

### "Cron runs but no Slack message"

**Problem**: Environment variables not available in cron.

**Solution**:
```bash
crontab -e

# Add at the top:
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
SLACK_CHANNEL=#morning-report

# Then your cron jobs...
```

## Security Best Practices

### 1. Protect Webhook URL

❌ **Don't**:
- Commit webhook URL to Git
- Share in public channels
- Include in screenshots
- Log to public logs

✅ **Do**:
- Store in environment variables
- Use `.env` file (add to `.gitignore`)
- Rotate periodically
- Limit who knows the URL

### 2. Webhook Rotation

Rotate webhook URLs every 90 days:

1. Create new webhook
2. Update environment variable
3. Test new webhook
4. Delete old webhook

### 3. Access Control

- Keep #morning-report private if handling sensitive data
- Limit webhook creation to admins
- Monitor webhook usage in Slack app settings

## Advanced Features

### Rich Message Blocks

For more interactive messages, edit `slack-formatter.ts` to use blocks:

```typescript
const blocks = [
  {
    type: 'header',
    text: { type: 'plain_text', text: '☀️ Morning Report' }
  },
  {
    type: 'section',
    text: { type: 'mrkdwn', text: '*System Health:* 95%' }
  },
  {
    type: 'actions',
    elements: [
      {
        type: 'button',
        text: { type: 'plain_text', text: 'View Dashboard' },
        url: 'http://45.61.58.125:9893'
      }
    ]
  }
];
```

### Threaded Replies

Send detailed metrics as thread replies:

```typescript
// First, send main message and get timestamp
const response = await fetch(webhookUrl, { ... });
const ts = response.ts;

// Then send threaded reply
await fetch(webhookUrl, {
  thread_ts: ts,
  text: 'Detailed metrics...'
});
```

### Slack App Features

Beyond webhooks, you can add:
- **Slash commands**: `/report morning`
- **Interactive buttons**: Acknowledge issues
- **Bot mentions**: `@DW-Agents status`
- **Home tab**: Dashboard in Slack

See: https://api.slack.com/start/building

## Getting Help

### Slack API Documentation
- Webhooks: https://api.slack.com/messaging/webhooks
- Message formatting: https://api.slack.com/reference/surfaces/formatting
- Block Kit: https://api.slack.com/block-kit

### Test Your Setup
```bash
cd /root/.claude/skills/daily-reporting
tsx daily-report-runner.ts test
```

### Check Logs
```bash
tail -f /root/DW-Agents/logs/morning-report.log
tail -f /root/DW-Agents/logs/eod-report.log
```

### Manual Test
```bash
cd /root/.claude/skills/daily-reporting
tsx daily-report-runner.ts morning
```

---

**Questions?** Check the main README.md or test with `tsx daily-report-runner.ts test`