Skip to main content

Discord rank-to-role sync

Platform guild Role rows (ranks) can map to multiple Discord role snowflakes for the linked Organization.discordServerId. Sync uses the existing bot (DiscordService.assignRole / removeRole). Event-based Discord roles (Event.discordRoleId, signup flows) stay separate: rank sync only touches roles listed in RoleDiscordRole.

Data model​

  • RoleDiscordRole: organizationRoleId → discordRoleId, optional sortOrder. Unique (organizationRoleId, discordRoleId).
  • DiscordManagedRoleSuppression: userId, organizationId, discordRoleId (optional discordGuildId). Unique (userId, organizationId, discordRoleId). Means: do not auto-add this Discord role for this user in this org until cleared.

Triggers​

  1. Rank change — membership.role.changed runs syncOnRankChange: removes Discord roles that belonged only to the previous rank, adds roles for the new rank (skips adds if suppressed).
  2. Discord account linked — After Better Auth updates User.discordId, notifyDiscordLinked runs reconcileAllForUser (full reconcile per active membership in orgs with a linked Discord server).
  3. guildMemberUpdate — If a managed Discord role (one mapped to the member’s current platform rank) disappears from the member, a suppression row is upserted so the next sync does not re-add it (mod or self-removal are indistinguishable without audit log).
  4. Manual — POST /api/v1/organizations/:guildId/discord-rank-roles/reconcile (officers).
  5. Scheduled — Daily at 05:00 UTC, reconcileAllOrganizationsWithRankMappings for orgs that have at least one RoleDiscordRole row.

Pausing sync: Organization.settings.discordRankRoleSyncEnabled — when explicitly false (Integrations toggle), triggers 1–5 skip Discord role changes for that guild; POST .../reconcile returns 400. Officers can still edit mappings and clear suppressions. Unset is treated as enabled for backward compatibility.

Reconcile vs rank change​

  • Rank change uses a diff between previous and new rank mappings (efficient).
  • Reconcile loads the member’s current Discord roles, intersects with all rank-managed role IDs for the org, then removes extras and adds missing (respecting suppressions).

Officer API​

  • GET /organizations/:guildId/discord-rank-roles — mappings keyed by platform role id.
  • PUT /organizations/:guildId/discord-rank-roles/roles/:roleId — body { discordRoleIds: string[] } (replace).
  • POST .../clear-suppressions — { userId } or { clearAll: true }.
  • POST .../reconcile — full org reconcile.

Requires Update Guild (same as other guild settings).

Operational constraints​

  • The bot’s highest role in Discord must be above any role it assigns.
  • Bot needs Manage Roles (already required for announcements/events).

Product policy​

Sticky suppression (default): once a managed role is removed in Discord, it is not re-added until an officer clears suppression for that user (or clearAll for the org).

Optional future: clear suppressions on platform rank change (not implemented; would “refresh” Discord packages on promotion).