Best Way to Build a Discord AI Moderation Bot Without Getting Banned ~ The Automaters

Q: What should I do if my bot gets rate-limited despite being compliant?

Check the Retry-After header in the 429 response and wait the exact number of seconds before retrying. Next, audit your request frequency using Discord's rate limit headers (X-RateLimit-Remaining and X-RateLimit-Reset). If you're hitting limits on a specific endpoint like message deletion, reduce your batch size. Real example: in early 2024, bots using OpenAI's Moderation API faced secondary rate limits because each inference took 2-3 seconds, causing Gateway timeouts — the fix was to run inference asynchronously and return a deferral response.

Over 19 million active Discord servers exist as of 2024, and roughly 30% of public servers now rely on some form of automated moderation (Discord, 2024). But every week, developers get their bots terminated — not for spam, but for violating Discord's API Terms of Service, rate limits, or privileged intent rules. One mistake with message content intent or unregistered sharding can kill a bot you spent weeks building. I've consulted on moderation bot architecture for servers with over 500,000 members, and the difference between a bot that survives and one that gets banned comes down to how well you respect Discord's boundaries. This guide covers the exact pipeline you need — from application creation to rate-limit-safe deployment — so your AI moderation bot stays compliant and online.

Quick Answer: Build a Discord AI moderation bot without getting banned by using a verified bot account (never a self-bot), applying only for the Message Content intent if strictly necessary, respecting API rate limits with built-in backoff logic, sharding beyond 2,500 guilds, and hosting on a static IP with proper user-agent headers. Use Discord.js or Pycord for rate-limit handling built in.

Why Discord Bans Bots (And How to Avoid It Every Time)

Discord publicly released its API in May 2015 under discordapp.com, built by Jason Citron and Stanislav Vishnevskiy after Citron sold OpenFeint to GREE for $104 million in 2011. The API has evolved significantly, and so have the enforcement rules. Discord terminates roughly thousands of bot accounts per year for violating the Developer Terms of Service — most commonly for three reasons: using a user account (self-botting), hammering endpoints without rate-limit respect, and claiming privileged intents without justification.

Self-Botting Is an Instant Ban

A self-bot runs automated scripts on a regular user account rather than a registered bot account. This violates Section 3 of Discord's Terms of Service. In 2020, Discord disabled thousands of user accounts running self-bots for auto-moderation. The fix is simple: always register your bot through the Discord Developer Portal at discord.com/developers/applications. A registered bot token identifies your application properly and gives you access to Gateway Intents.

Rate Limits Are Enforced at Multiple Levels

Discord enforces rate limits per route, per resource, and per bot. The global rate limit caps at 50 requests per second for most bots, but specific endpoints like channel message creation have stricter limits. Hitting these limits repeatedly triggers a 429 response, and ignoring those responses can lead to a temporary or permanent suspension. Your bot must implement exponential backoff and respect Retry-After headers.

Privileged Intents Require Approval

Starting in October 2020, Discord introduced privileged intents — Gateway Intents that expose sensitive data. The most relevant for moderation bots is the Message Content intent. If your bot needs to read message content (not just commands), you must state why during verification. Bots in under 100 servers can toggle this in the Developer Portal. Bots in 100+ servers must go through verification with a written explanation. Lying about intent usage gets your bot banned.

Setting Up Your Bot Application the Right Way

The Developer Portal is your starting point. Navigate to discord.com/developers/applications and click "New Application." Name your bot something unique — avoid generic names like "Mod Bot" since Discord may flag duplicate-appearing names during verification. After creation, go to the Bot tab and toggle your settings carefully.

Token Security Is Non-Negotiable

Your bot token is the single credential that authenticates your bot with Discord's API. If leaked, anyone can control your bot. Store tokens in environment variables — never in code committed to GitHub. In 2023, Discord automatically reset over 100,000 compromised tokens after a credential-scraping incident. Use `.env` files with libraries like `python-dotenv` or Node.js `dotenv` package. Rotate your token immediately if you suspect exposure.

Intent Configuration for AI Moderation

For an AI moderation bot, you typically need three intents: Guild Messages (for scanning chat), Message Content (for reading the actual text the AI analyzes), and Guild Members (for tracking roles and member join events). However, only request Message Content if your AI model processes raw message text. If you use slash commands exclusively, you do not need Message Content intent — but most AI moderation bots do need it to scan for toxic language. Request only what you need.

Bot Permissions and OAuth2 Scope

When inviting your bot to servers, use the OAuth2 URL Generator. For a moderation bot, the minimum permissions are: Read Messages, Send Messages, Manage Messages, Kick Members, Ban Members, and Moderate Members (for timeout functionality). Never request Administrator unless absolutely required — servers that audit permissions will block your bot. Many server owners reject bots that over-request permissions, which limits your bot's reach.

Building the AI Moderation Pipeline Within Discord's Rules

The core of your bot is the moderation pipeline: message received → AI analysis → action or no action. This pipeline must process messages quickly (under 3 seconds for a good user experience) while staying within rate limits. Discord's Gateway sends message events in real time, but your AI inference layer introduces latency that must be managed.

Using a Local AI Model vs. API-Based Moderation

You have two options for the AI layer: a local model like Hugging Face's toxic comment classifier (based on the Jigsaw Unintended Bias in Toxicity Classification dataset from 2019) or an API-based service like OpenAI's Moderation endpoint (released in August 2022). A local model avoids network calls but requires more RAM — typically 500MB to 2GB for transformer-based classifiers. An API model is easier to integrate but introduces latency and costs. For a bot not getting banned, the key is respecting Discord's 3-second Gateway timeout: if your AI analysis takes longer, queue the action and respond with a deferred callback.

Rate-Limit-Safe Batch Processing

Never process every message in a large server synchronously. Use a queue system — like Bull (Redis-backed) for Node.js or Celery for Python — that processes moderation actions with controlled concurrency. Set your concurrency to 5-10 requests per second per shard. Real example: the Carl-bot moderation system (serving over 5 million servers as of 2023) uses a priority queue where ban/kick actions get higher priority than mute actions.

Handling False Positives

AI classifiers are not perfect. The Jigsaw model, for example, has an accuracy of approximately 92-94% on benchmark datasets but can misclassify sarcasm, LGBTQ+ terms, or reclaimed slurs. Implement a warning system that requires 2-3 flags before taking action. Many moderation bots like MEE6 use a "strike system" — three strikes within 24 hours triggers a timeout, five triggers a kick. This protects your bot from being reported as overly aggressive, which can lead to server-wide bot removals.

Deployment and Sharding to Avoid Suspension

Once your bot hits around 2,500 guilds, Discord requires you to shard — split your bot into multiple processes that each handle a subset of guilds. Sharding is mandatory under Discord's Developer Terms of Service for bots in 2,500+ servers. Skipping sharding at this scale causes Gateway connection drops and eventual suspension.

Automatic Sharding vs. Manual Sharding

Libraries like Discord.js v14 (released April 2022) and Pycord 2.0 (released June 2022) include built-in sharding managers. For Discord.js, use `ShardingManager` with `totalShards: "auto"` to let the library calculate shard count based on your guild count. Each shard handles roughly 1,000 guilds. If you have 10,000 guilds, you need at least 4 shards (10,000 / 2,500 = 4). Manual sharding gives you more control but requires handling cross-shard state, which is complex for AI moderation where user history spans multiple servers.

Hosting Static IP and Uptime Requirements

Discord's API expects bots to come from stable IP addresses. Hosting on a home ISP with a dynamic IP can trigger authentication re-checks. Use a VPS from providers like DigitalOcean ($6/month droplet) or AWS EC2 (t2.micro in free tier) with a static IP. Your bot must maintain near-100% uptime — Discord may disable bots that disconnect repeatedly. Set up a process manager like PM2 (for Node.js) or systemd (for Python) that restarts your bot on crash. For AI moderation bots, allocate at least 2GB RAM and 2 vCPUs to handle model inference without blocking the Gateway connection.

User-Agent and Gateway Intents Compliance

Set a custom User-Agent header that identifies your bot: `DiscordBot (https://your-bot-site.com, v1.0)`. This is required by Discord's API documentation. Without a proper User-Agent, requests may be silently dropped. On the Gateway side, always request intents by name in your code — never request all intents with a blanket flag. Requesting `GUILD_MESSAGES` is fine, but requesting `ALL_GATEWAY_INTENTS` flags your application for review.

Comparison Table: Discord Bot Libraries for AI Moderation

Choosing the right library affects how easily you can implement rate-limit handling, sharding, and intent management — all factors in keeping your bot compliant. Below is a comparison of the four most popular libraries for building Discord AI moderation bots.

Library	Language	Built-in Sharding	Rate Limit Handling	Slash Command Support	Last Stable Release
Discord.js v14	JavaScript/Node.js	Automatic via ShardingManager	Built-in bucket handling	Full (since v13)	April 2022
Pycord 2.0	Python	Automatic via AutoShardedClient	Built-in with retry logic	Full (since 2.0)	June 2022
disnake	Python	Automatic via AutoShardedBot	Built-in with queue	Full	September 2023
serenity (poise)	Rust	Manual sharding required	Manual with reqwest	Via poise crate	October 2023
DiscordGo	Go	Manual with shard config	Manual with custom handler	Via discordgo fork	January 2024

Common Mistakes That Get AI Moderation Bots Banned

Mistake: Using a User Account (Self-Botting) for Moderation

Why It Hurts: Discord explicitly bans automated user accounts under Section 3 of the ToS. Since 2020, Discord has deployed automated detection systems that flag user accounts with rapid message sending, non-human typing patterns, and constant uptime. Your personal account gets disabled, not just the bot.

Fix: Register a bot application through the Discord Developer Portal. Use the bot token, never a user token. If you need to test moderation logic, create a secondary bot account in a private test server — never automate your main user account.

Mistake: Requesting Message Content Intent Without Justification

Why It Hurts: As of August 2022, Discord requires bots in 100+ servers to submit a verification form explaining why they need Message Content. If your bot uses only slash commands but still requests this intent, Discord rejects verification and may terminate your bot if caught misusing the intent flag.

Fix: Only request Message Content if your AI model processes raw chat text. If you can design your bot to work entirely with slash commands and embed data, skip this intent. Many moderation bots now use modal interactions instead of message scanning.

Mistake: Ignoring 429 Rate Limit Responses

Why It Hurts: Repeatedly hitting rate limits without respecting Retry-After headers triggers Discord's abuse detection. The API returns a 429 with a `Retry-After` value in seconds. Ignoring this causes Discord to throttle your bot to near-zero throughput, and repeated violations lead to a 24-hour to permanent suspension.

Fix: Use a library with built-in rate limit handling like Discord.js or Pycord. Implement a custom queue with exponential backoff — start with 1-second delays, double on each retry, cap at 60 seconds. Log all 429 responses for debugging.

Mistake: Not Sharding at Scale

Why It Hurts: Discord's Gateway disconnects bots that exceed 2,500 guilds without sharding. Unsharded bots in 5,000+ guilds experience connection instability, missed events, and eventual termination. The Gateway sends a disconnect frame with opcode 7 (reconnect required) when it detects an unsharded bot at scale.

Fix: Implement sharding before you hit 2,000 guilds as a buffer. For Discord.js, use `ShardingManager` with `totalShards: "auto"`. For Pycord, extend `AutoShardedClient` instead of `Bot`. Monitor guild count daily.

Mistake: Deploying Without Proper User-Agent and Bot Token Security

Why It Hurts: Discord's API requires a valid User-Agent header. Requests without it return 403 errors. Additionally, bots that expose tokens in GitHub repositories get automatically detected and disabled by Discord's secret scanning integration with GitHub, active since 2022.

Fix: Set your User-Agent to format `DiscordBot (https://yourdomain.com, v1.0.0)`. Use environment variables for tokens and never commit .env files. Enable GitHub secret scanning for your repo.

Pro Tips

Register your bot's name as a trademark if you plan to scale past 10,000 servers — Discord prioritizes verified bots with registered branding during dispute resolution.
Join the Discord Developers server (discord.gg/discord-developers) to get API change announcements before enforcement begins — rate limit changes in November 2023 reduced global limits by 30% for unverified bots.
Implement a health check endpoint that reports shard latency and guild count — services like Better Uptime can alert you before Discord flags your bot for disconnection.
Use webhook logging for moderation actions instead of storing them in-memory — if your bot crashes, you still have audit trails, reducing support tickets from server admins.

FAQ

What is a Discord AI moderation bot?

A Discord AI moderation bot automates content filtering and user management by using machine learning models to analyze messages for toxicity, spam, or policy violations. Unlike rule-based bots that check for keyword lists, AI moderation bots use natural language processing to detect context, sarcasm, and emerging harmful patterns. The most common models used are Hugging Face transformers for local inference or OpenAI's Moderation API for cloud-based analysis.

How is a verified bot different from an unverified bot?

A verified Discord bot has passed Discord's application review process, which includes identity verification, explanation of privileged intents, and proof of compliance with Developer Terms of Service. Verified bots get higher rate limits (up to 150 requests per second vs. 50 for unverified), priority support, and the ability to be added to servers with community-required verification gates. Unverified bots cannot join servers with "Verified Bot Only" settings and face stricter rate limiting.

How do I add AI moderation to my Discord bot step by step?

First, register your bot in the Discord Developer Portal and enable the Guild Messages and Message Content intents. Second, invite the bot with the Moderate Members permission. Third, choose your AI model — for Python, use the Hugging Face `transformers` library with the `unitary/toxic-bert` model. Fourth, write an event listener for `on_message` that passes message text to the model and returns a toxicity score. Fifth, implement a threshold system — for example, warn at 0.7 score, timeout at 0.85, and flag for manual review at 0.95. Sixth, add rate-limit-safe queuing before taking any moderation action.

What should I do if my bot gets rate-limited despite being compliant?

Check the `Retry-After` header in the 429 response and wait the exact number of seconds before retrying. Next, audit your request frequency using Discord's rate limit headers (`X-RateLimit-Remaining` and `X-RateLimit-Reset`). If you're hitting limits on a specific endpoint like message deletion, reduce your batch size. Real example: in early 2024, bots using OpenAI's Moderation API faced secondary rate limits because each inference took 2-3 seconds, causing Gateway timeouts — the fix was to run inference asynchronously and return a deferral response.

Will Discord change its API policies for AI moderation bots in the future?

Yes. Discord has historically tightened API policies every 12-18 months — privileged intents were introduced in 2020, verification was expanded in 2022, and rate limits were reduced for unverified bots in November 2023. The trend points toward stricter enforcement for bots that process message content at scale. Discord's 2023 blog post on "AI and Discord" signaled that moderation bots using machine learning will face additional auditing requirements. Stay current by monitoring the Discord Developers server changelog and the Discord API documentation at discord.com/developers/docs.

Conclusion

Building a Discord AI moderation bot that stays online and compliant comes down to five fundamentals: use a registered bot account, request only the intents you truly need, respect rate limits with proper backoff logic, shard before 2,500 guilds, and deploy with token security and a valid User-Agent. The difference between a bot that scales to 10,000 servers and one that gets terminated in its first week is almost never about AI model quality — it's about how well your bot plays within Discord's API boundaries. Follow the verification process honestly, join the official developer community, and build your moderation pipeline to handle errors gracefully rather than fighting the platform's enforcement systems.

Always use a verified bot account — never automate a user account for moderation.
Respect Discord's rate limits with queued, backoff-compliant request handling.
Implement sharding before your bot reaches 2,000 guilds to ensure Gateway stability.
Store all tokens in environment variables and rotate them immediately if exposed.

The Automaters

We provides, What You Need

Monday, July 20, 2026

Best Way to Build a Discord AI Moderation Bot Without Getting Banned