Discord Sync

Discord Sync (Smart Router)

Automatically detects available tokens and bot permissions to route to the optimal sync connector.

When to Use

• User asks to "sync Discord messages"
• User asks to "pull messages from Discord"
• User wants to "get Discord history"
• User wants to "update Discord data"
• User wants to "download Discord messages"
• User asks to "fetch messages from #channel"

How It Works

This skill runs a preflight check before syncing:

1. Token Detection - Checks which tokens are configured in .env
2. Token Validation - Verifies tokens are valid by calling Discord API
3. Permission Check - For bot token, verifies server access and required permissions
4. Smart Routing - Recommends the optimal connector based on results

Routing Logic

How to Execute

Step 1: Run Preflight Check

# Check for specific server
python ${CLAUDE_PLUGIN_ROOT}/tools/discord_preflight.py --server SERVER_ID

# Check for DM sync
python ${CLAUDE_PLUGIN_ROOT}/tools/discord_preflight.py --dms

# JSON output for programmatic use
python ${CLAUDE_PLUGIN_ROOT}/tools/discord_preflight.py --server SERVER_ID --json

Step 2: Route Based on Result

The preflight check returns a recommendation. Execute the recommended skill:

If recommendation is discord-bot-connector:discord-sync:

Skill(skill: "discord-bot-connector:discord-sync")

If recommendation is discord-user-connector:discord-sync:

Skill(skill: "discord-user-connector:discord-sync")

Example Preflight Output

==================================================
Discord Sync Preflight Check
==================================================

Token Status:
  User Token: valid
  Bot Token:  valid

Bot Permissions:
  Server: My Community Server
  Has Access: Yes
  View Channels: Yes
  Read History: Yes

Recommendation:
  Use: discord-bot-connector:discord-sync
  Reason: Bot has access to My Community Server with required permissions (faster sync)

Preflight JSON Output

{
  "user_token": {"configured": true, "valid": true, "error": null},
  "bot_token": {"configured": true, "valid": true, "error": null},
  "bot_permissions": {
    "server_id": "123456789",
    "server_name": "My Community Server",
    "has_access": true,
    "can_view_channels": true,
    "can_read_history": true,
    "error": null
  },
  "wants_dms": false,
  "recommendation": "discord-bot-connector:discord-sync",
  "reason": "Bot has access to My Community Server with required permissions (faster sync)"
}

Smart Defaults

When user is vague, use these defaults:

Prerequisites

• .env file with at least one Discord token:
  • DISCORD_USER_TOKEN - For user token sync (servers + DMs)
  • DISCORD_BOT_TOKEN - For bot token sync (servers only, faster)
• aiohttp library installed for API calls

Connector Comparison

Troubleshooting

Bot token valid but "lacks permissions":

• Ensure bot has "Read Message History" permission in Discord
• Check if bot role is above restricted channels
• Try re-inviting bot with correct permissions

User token invalid:

• Token may have expired - get a new one
• Ensure token is copied correctly (no extra spaces)

No tokens configured:

• Create .env file in project root
• Add DISCORD_USER_TOKEN=your_token or DISCORD_BOT_TOKEN=your_token