Skip to main content

Battle.net & Discord Integration Guide

1. Authentication (OAuth) - User Login​

Battle.net OAuth Setup​

  1. Create Battle.net API Client:

  2. Update apps/api/.env:

    BATTLENET_CLIENT_ID=your_client_id
    BATTLENET_CLIENT_SECRET=your_secret
    BATTLENET_CALLBACK_URL=http://localhost:3000/api/v1/auth/battlenet/callback

  3. Test: Visit http://localhost:3000/api/v1/auth/battlenet

Discord OAuth Setup​

  1. Create Discord App: https://discord.com/developers/applications
  2. OAuth2 → Add redirect: http://localhost:3000/api/v1/auth/discord/callback
  3. Update .env with Client ID and Secret
  4. Test: Visit http://localhost:3000/api/v1/auth/discord

Discord Server Connection (Guild Settings UI)​

Guild managers can connect a Discord server to their guild via Guild Settings → Integrations (/guilds/:id/settings/integrations). The UI lets them enter a Discord Server ID and, once connected, browse the server's available channels and roles. This data is fetched from the Discord API via GET /api/v1/discord/:guildId/channels and /roles.

2. External API Data Fetching (Background Jobs)​

Overview​

The JobsModule stub is ready for background ingestion of:

  • Battle.net API: Guild roster, character profiles, realm status
  • Discord API: Guild member list, roles sync
  • Raider.IO API: Mythic+ scores, raid progress

Battle.net Game Data API​

Key endpoints for guild management:

// Example: Fetch guild roster
GET https://us.api.blizzard.com/data/wow/guild/{realm-slug}/{guild-name-slug}/roster
Headers: Authorization: Bearer {access_token}

// Example: Fetch character profile
GET https://us.api.blizzard.com/profile/wow/character/{realm-slug}/{character-name}

Implementation pattern:

  • Store guild realm + name in database
  • Background job refreshes roster every 6-24 hours
  • Never call Blizzard API during user requests (always read cached DB data)
  • Use BullMQ + Redis for job queue

Discord Guild API​

Key endpoints:

// Fetch Discord guild members
GET https://discord.com/api/v10/guilds/{guild-id}/members
Headers: Authorization: Bot {bot-token}

// You need a Discord Bot for this (different from OAuth app)

Implementation pattern:

  • Store Discord server ID in Guild table
  • Background job syncs member list
  • Match Discord users to Battle.net accounts via linked accounts table

Raider.IO API​

Public API (no auth required):

// Guild progress
GET https://raider.io/api/v1/guilds/profile?region=us&realm={realm}&name={guild-name}&fields=raid_progression,raid_rankings

// Character scores
GET https://raider.io/api/v1/characters/profile?region=us&realm={realm}&name={name}&fields=mythic_plus_scores_by_season:current

Implementation pattern:

  • Fetch on-demand or via background jobs
  • Cache for 1-6 hours (Raider.IO updates frequently)
  • Display in guild/character detail pages

3. Implementation Roadmap​

Phase 1: OAuth (✅ Done)​

  • Battle.net login
  • Discord login
  • JWT tokens

Phase 2: Guild Data Ingestion​

  1. Add BullMQ + Redis to JobsModule
  2. Create GuildRosterJob - fetches roster from Battle.net
  3. Store characters and memberships
  4. Schedule: runs every 6 hours

Phase 3: Discord Sync​

  1. Create Discord Bot
  2. Add DiscordSyncJob - syncs guild members
  3. Link Discord users to Battle.net accounts
  4. Schedule: runs every 30 minutes

Phase 4: Raider.IO Integration​

  1. Add RaiderIOJob - fetches scores
  2. Store in PerformanceMetrics table (extension domain)
  3. Display on character/guild pages

Phase 5: Real-time Updates (Future)​

  • Discord webhooks for member joins/leaves
  • Battle.net webhooks (if available)
  • WebSocket updates to frontend

4. Next Steps (Immediate)​

  1. Get OAuth credentials:

  2. Test login flows:

    • Visit /api/v1/auth/battlenet
    • Visit /api/v1/auth/discord
    • Verify JWT works at /api/v1/auth/me

  3. Add BullMQ for background jobs:

    cd apps/api
    pnpm add @nestjs/bullmq bullmq ioredis

  4. Create first job: Guild Roster Sync

    • Fetch roster from Battle.net
    • Create/update User records
    • Create Membership records
    • Link to Guild