Rock Pigeon ATS - Discord Integration Activation

This checklist covers the steps to activate Discord notifications for candidate stage changes in Rock Pigeon ATS.

Prerequisites

Access to Discord Developer Portal
Access to Rock Pigeon ATS server/environment variables
Access to discord-integrations repository (for bot token)

Security: Rotate Exposed Token

Go to Discord Developer Portal
Find the Cadence Admin Bot (Pingbot) application
Navigate to Bot → Reset Token
Copy the new token
Update discord-integrations/features/pingbot/bot/.env:
```
DISCORD_BOT_TOKEN=new_token_here
```

Redeploy affected workers:

cd discord-integrations
./scripts/deploy-all.sh

Get Discord Channel ID

Enable Developer Mode in Discord:
- User Settings → App Settings → Advanced → Developer Mode: ON
Right-click on the channel where you want hiring notifications
Click Copy Channel ID

Configure Rock Pigeon ATS

Add the following to Rock Pigeon’s .env file:

# Discord Integration (Phase 1 - Stage Change Notifications)
DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_CHANNEL_ID=your_channel_id_here
DISCORD_GUILD_ID=1442608946652385394

Where to get values:

Variable	Source
`DISCORD_BOT_TOKEN`	`discord-integrations/features/pingbot/bot/.env`
`DISCORD_CHANNEL_ID`	Copy from Discord (see above)
`DISCORD_GUILD_ID`	Cadence Discord server ID (pre-filled)

Verify Installation

Start the queue worker (if not already running):
Terminal window
```
php artisan queue:work
```
Test by changing a candidate’s stage in the ATS
Verify notification appears in Discord channel:

🎤 John Smith moved to Interview for Senior Engineer

Previous stage: Resume Review

Troubleshooting

No notification appears

Check queue worker is running
Verify DISCORD_BOT_TOKEN is set correctly
Check Laravel logs: storage/logs/laravel.log
Verify bot has permission to post in the channel

“Unauthorized” error in logs

Bot token is invalid or expired
Regenerate token in Discord Developer Portal

“Channel not found” error

Channel ID is incorrect
Bot doesn’t have access to that channel
Verify bot is in the correct server

Future Phases (Not Yet Implemented)

Phase 2: Candidate discussion threads (private threads per candidate)
Phase 3: Evaluation reminder DMs to panel members
Phase 4: Decision summaries when all evaluations are in

Technical Details

Code Location: rock-pigeon-ats/app/Discord/

Event Flow:

UpdateCandidateStageAction updates stage
CandidateStageChanged event dispatched
NotifyDiscordOnStageChange listener (queued) sends to Discord

Graceful Degradation: If DISCORD_BOT_TOKEN is not set, a null service is used and no notifications are sent (app continues to work normally).