Fairness & Tracking
Tracking modes, fairness rules, and session flow.
AttendiBot tracks voice channel participation through Discord voice state events (join, leave, move). This document explains tracking modes, fairness rules, and what data is stored.
What AttendiBot tracks
AttendiBot records metadata only:
| Field | Description |
|---|---|
| User ID | Discord user who participated |
| Channel ID | Voice channel |
| Guild ID | Discord server |
| Join timestamp | When the user entered the channel |
| Leave timestamp | When the user exited |
| Duration | Accumulated voice time (seconds) |
| Session UUID | Unique session identifier |
| Signature | Ed25519 signature of the session payload |
AttendiBot never records, stores, or transmits voice audio.
Voice state event flow
- Join — user enters a tracked voice channel → active session created
- Move — user switches channels → old session finalized, new session started (if new channel is tracked)
- Leave — user disconnects from voice → session finalized, signed, and persisted
During an active session, fairness rules continuously determine whether time accrues.
Tracking modes
Configure in Settings → Tracking or /admin tracking-mode.
| Mode | Behavior | Use case |
|---|---|---|
| Off | No tracking | Maintenance or temporary disable |
| Allowlist | Track only listed channels | Study halls, official meeting rooms |
| Denylist | Track all except listed channels | Exclude AFK and lobby channels |
| All | Track every voice channel | Small servers with few channels |
Allowlist / Denylist channel management
Add or remove channels via the dashboard or:
/admin track-channel action:Add channel:#Study-Hall
/admin track-channel action:Remove channel:#AFK
/admin track-channel action:ShowIn Allowlist mode, only listed channels are tracked. In Denylist mode, all channels except listed ones are tracked.
Fairness settings
Fairness rules control when voice time counts toward attendance. Configure in Settings → Tracking → Fairness.
| Setting | Default | Description |
|---|---|---|
| Pause on mute | Off | Stop counting when user is server-muted or self-muted |
| Pause on deafen | Off | Stop counting when user is server-deafened or self-deafened |
| Pause when solo | Off | Stop counting when user is alone in the channel |
| Minimum session duration | 0 seconds | Sessions shorter than this are not recorded |
How fairness works during a session
While a user is in a tracked channel, AttendiBot evaluates voice state flags on each update:
- If pause on mute is enabled and the user is muted → time stops accruing
- If pause on deafen is enabled and the user is deafened → time stops accruing
- If pause when solo is enabled and the user is the only member → time stops accruing
When conditions clear (unmute, others join), counting resumes from that point.
Minimum session duration
After a session ends, if total duration is below min_session_seconds, the session is discarded entirely. Useful for filtering accidental joins or brief channel hops.
Period leaderboards
Voice time accumulates within the current period. When a period resets:
- All session times are totaled per user
- A signed period snapshot is archived
- Leaderboard counters reset to zero
Configure reset intervals in Settings → Periods. See Getting Started.
Permissions required
The bot needs:
- View Channels — see voice channels
- Connect — detect voice state (does not need to stay connected)
- Send Messages + Embed Links — for log destinations
Admin configuration requires Manage Server on the guild.