Skip to main content

Discord Bot Guide

This guide explains how to set up and use the Kim Discord bot, including verification types, server configuration, and direct interactions with the bot.

Overview​

  • Supported stakeholders: server admins, moderators, verifiers, community members
  • Capabilities: verification (voice/text), submissions, moderation helpers

Setup​

  • Invite the bot to your server (admin permissions recommended)
  • Assign required roles/permissions
  • Configure channels for verification and submissions

Verification Types​

  • Levels explained (text and voice)
  • Evidence requirements, examples, and acceptance criteria

Verify Voice​

  • Recording and uploading guidance
  • Privacy notes
  • Expected turnaround and results

Verify Text​

  • Supported formats
  • Context and metadata required
  • Review flow

Direct Verification with Bot​

  • DM commands
  • Rate limits and anti-abuse

Server Configuration​

  • Role mapping (verifiers, reviewers, submitters)
  • Channel structure recommendations
  • Logging and audit trails

Best Practices​

  • Safety & privacy
  • Avoiding false positives
  • Escalation paths

Screenshots: Add sanitized images here (metadata scrubbed).

Testing the KimGate Discord bot​

Quick guide: test the KimGate Discord bot​

Discord Test Server (invite): https://discord.gg/sfqWR9xBcf

Add KimGate to a server: Authorize KimGate

Prereqs (once, by a server admin)​

  • Ensure the bot is online in your server.
  • Create or choose two roles to represent verified and unverified members (names are up to you; examples used here are Verified and Unverified).
  • Move the bot’s highest role above both chosen roles in Server Settings → Roles.
  • Verify the bot has these permissions in the server: Manage Roles, Kick Members, Send Messages, Use Slash Commands.
Why role order matters

Discord only lets a bot manage roles that are lower than the bot’s highest role. If assignments fail, move the bot’s role higher.

Add screenshots here after you capture them and place into static/img/kimgate/:

  • Role hierarchy example: ![Role order example](/img/kimgate/role-order.png)
  • Permissions example: ![Channel permissions example](/img/kimgate/channel-permissions.png)
  • Debug output example: ![Debug checklist example](/img/kimgate/debug-status.png)

1) Admin setup and sanity checks​

  • Run initial setup (server admin)

    • Use: /setup verified_role:@<YourVerifiedRole> unverified_role:@<YourUnverifiedRole> timeout:5 (you can use any existing roles; names are just examples)
    • Set a log channel: /kimlogchannel set #kim-log (or any text channel)
    • Validate everything: /debug (check required permissions and role hierarchy show ✅)

You can illustrate these steps with screenshots placed at:

  • /img/kimgate/log-channel.png (log channel set)

  • /img/kimgate/debug-status.png (debug output)

  • Optional admin checks

    • See your admin status: /whoami
    • Add a server admin: /serveradmin add @user (server admins only)
    • Add a global admin: /globaladmin add @user (bot owner/bot admin only)

2) How regular users can test verification​

  • Join test

    • Have a test user join your server. They should automatically receive your configured unverified role.
    • The bot will initiate verification (DMs). Complete the steps.
    • On success, the user should get your configured verified role and lose the unverified role.

  • Re-test a user

    • Clear a user’s state: /reset @user, then remove their verified role and re-run the join/flow as needed.
    • See recent verification events: /kimstats recent
    • If someone failed verification: /failed

3) Testing phrase and moderation features​

  • Phrases

    • Add a phrase: /kimphrases add phrase:some phrase
    • List phrases: /kimphrases list
    • Remove a phrase: /kimphrases remove phrase:some phrase
    • Reset to defaults: /kimphrases reset

  • Flags and bans

    • Flag a user: /flag @user reason:Testing
    • View flags: /flags @user
    • Unflag: /unflag @user
    • List all flagged: /flagged
    • Bot-admin only (global): /flag-global @user, /flags-global @user, /unflag-global @user, /flagged-global
    • Bot-admin only (ban): /ban @user, /unban @user

  • Analytics and audits

    • Server stats: /kimstats stats
    • Global stats (bot admin only): /kimstats global
    • Leaderboard: /kimstats leaderboard
    • Audit log (last 20 admin/verification events): /kimstats audit
    • Export by period: /kimstats export duration:7d (examples: 24h, 7d, 30d)

4) Let users "add to their channels" and test there​

  • By default, the bot can act wherever it can see and speak. To allow the bot in a specific channel:

    • Right-click the channel → Edit Channel → Permissions.
    • Add the bot’s role (or the bot user) → Allow at least: View Channel, Send Messages, Read Message History.
    • If the channel is private, ensure the bot’s role is explicitly added and allowed.
    • Re-run /debug if the bot still can’t speak or manage roles there.

  • For log delivery, ensure the chosen log channel allows the bot to Send Messages, then set it with /kimlogchannel set #channel.

Add a permissions screenshot if needed: ![Grant bot permissions](/img/kimgate/grant-permissions.png)

5) Troubleshooting​

  • Roles not being assigned

    • Run /debug and confirm:
      • Manage Roles is ✅
      • Bot role is above your chosen verified/unverified roles in the hierarchy
    • Re-run /setup if you changed roles.

  • Bot not responding in a channel

    • Check the channel’s permissions for the bot role (View Channel, Send Messages).
    • Confirm the bot is not timed out/muted and can Use Slash Commands.

  • Verification didn’t start on join

    • Confirm /setup was completed and shows ✅ in /debug.
    • Check the log channel for warnings.
    • Use /reset @user and try again.

  • Admin permission errors

    • Use /whoami to see what the bot thinks you are.
    • Ensure you’re a server admin (Discord Administrator permission) or added via /serveradmin add @you.

  • See what’s happening

    • Use /kimstats audit and /kimstats recent to inspect recent actions and verification attempts.

6) Minimal end-to-end test checklist​

  • Admin runs /setup and /kimlogchannel set #kim-log → /debug shows ✅
  • New test user joins → gets Unverified → completes verification → gets Verified
  • Admin runs /kimphrases add, /kimphrases list → phrase visible
  • Admin flags a user /flag @user → /flags @user shows count → /unflag @user clears
  • Admin checks /kimstats stats, /kimstats audit, /kimstats recent show activity
  • Admins can test in any channel by granting the bot’s role channel permissions as described above.
  • For a full command reference, use /help (admin-only).