How to Automate Discord Server Moderation using the API

Understanding the Discord API

Setting Up Discord API Authentication

Bot tokens are static credentials. For content-based moderation, you must enable the MESSAGE_CONTENT privileged intent in both the Developer Portal and your bot code. Bots under 75 guilds self-enable via the portal. At 75+ guilds you can apply for the intent. At 100+ guilds, Discord requires full bot verification. Without this intent, content fields in MESSAGE_CREATE events are empty strings.

1. 1Go to https://discord.com/developers/applications and click New Application.
2. 2Open the Bot tab. Click Reset Token — copy it immediately.
3. 3Under Privileged Gateway Intents, toggle on Message Content Intent. Also toggle Server Members Intent if you need member join events.
4. 4Open OAuth2 > URL Generator. Select scopes: bot and applications.commands.
5. 5Under Bot Permissions, check: Moderate Members, Ban Members, Kick Members, Manage Messages, Send Messages, View Channels, Read Message History.
6. 6Copy the generated URL and invite the bot to your server.
7. 7In your server's role settings, drag the bot's role above every member role it needs to moderate.
8. 8Store DISCORD_BOT_TOKEN, DISCORD_GUILD_ID, and DISCORD_MOD_LOG_CHANNEL_ID in environment variables.

1import os
2import discord
3
4# discord.py v2.7.1 — pip install discord.py
5BOT_TOKEN = os.environ["DISCORD_BOT_TOKEN"]
6
7# All three privileged intents
8intents = discord.Intents.default()
9intents.message_content = True  # Required for reading message text
10intents.members = True           # Required for member events
11
12client = discord.Client(intents=intents)
13
14@client.event
15async def on_ready():
16    print(f"Moderation bot connected as {client.user}")
17    print(f"MESSAGE_CONTENT intent: {client.intents.message_content}")
18
19client.run(BOT_TOKEN)

Key endpoints

1{"communication_disabled_until": "2026-05-08T10:00:00+00:00"}

1{"user":{"id":"123456789","username":"spammer"},"roles":[],"communication_disabled_until":"2026-05-08T10:00:00+00:00","joined_at":"2026-01-01T00:00:00.000Z"}

1204 No Content

1{"delete_message_seconds": 86400}

1204 No Content

1{"embeds":[{"title":"Moderation Action","color":16711680,"fields":[{"name":"Action","value":"Timeout (1h)","inline":true},{"name":"User","value":"<@123456789>","inline":true},{"name":"Reason","value":"Spam: 5 identical messages in 10s","inline":false}]}]}

1{"id":"998877665","channel_id":"mod_log_id","embeds":[{"title":"Moderation Action"}]}

Step-by-step automation

1# Verify bot application flags (includes whether intents have been approved)
2curl -s -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
3  "https://discord.com/api/v10/applications/@me" \
4  | python3 -c "import sys,json; d=json.load(sys.stdin); print('Flags:', d.get('flags', 0))"

1# No direct cURL equivalent — this is application logic
2# Test your rules by sending test messages through the bot manually

1# Timeout a member for 1 hour
2EXPIRY=$(date -u -d '+1 hour' '+%Y-%m-%dT%H:%M:%S+00:00')
3curl -X PATCH \
4  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
5  -H "Content-Type: application/json" \
6  -d "{\"communication_disabled_until\": \"$EXPIRY\"}" \
7  "https://discord.com/api/v10/guilds/$GUILD_ID/members/$USER_ID"
8
9# Ban a member and delete last 24 hours of messages
10curl -X PUT \
11  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
12  -H "Content-Type: application/json" \
13  -d '{"delete_message_seconds": 86400}' \
14  "https://discord.com/api/v10/guilds/$GUILD_ID/bans/$USER_ID"

1# Check current ban list size as a raid indicator
2curl -s -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
3  "https://discord.com/api/v10/guilds/$GUILD_ID/bans?limit=100" \
4  | python3 -c "import sys,json; print(f'Bans: {len(json.load(sys.stdin))}')"

Complete working code

A complete discord.py moderation bot that monitors all messages, checks them against configurable rules, applies progressive moderation actions (timeout, kick, ban), logs all actions to a mod-log channel, and includes a raid circuit breaker to prevent rate-limit exhaustion during coordinated attacks.

1import os, time, logging, requests
2from datetime import datetime, timedelta, timezone
3from collections import defaultdict, deque
4import discord
5
6logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
7
8BOT_TOKEN = os.environ["DISCORD_BOT_TOKEN"]
9GUILD_ID = os.environ["DISCORD_GUILD_ID"]
10MOD_LOG = os.environ["DISCORD_MOD_LOG_CHANNEL_ID"]
11BASE = "https://discord.com/api/v10"
12H = {"Authorization": f"Bot {BOT_TOKEN}", "Content-Type": "application/json"}
13
14intents = discord.Intents.default()
15intents.message_content = True
16intents.members = True
17client = discord.Client(intents=intents)
18
19user_history = defaultdict(lambda: deque(maxlen=10))
20action_times = deque()
21BANNED_WORDS = ["badword1"]
22MAX_ACTIONS_PER_MIN = 20
23
24def circuit_breaker_ok():
25    now = time.time()
26    while action_times and now - action_times[0] > 60:
27        action_times.popleft()
28    return len(action_times) < MAX_ACTIONS_PER_MIN
29
30def check_violation(message):
31    content = message.content.lower()
32    uid = str(message.author.id)
33    now = datetime.now(timezone.utc)
34    for word in BANNED_WORDS:
35        if word in content:
36            return ("timeout", 3600, f"Banned word: {word}")
37    history = user_history[uid]
38    history.append((now, content))
39    recent_identical = sum(1 for ts, c in history if (now-ts).seconds < 30 and c == content)
40    if recent_identical >= 5:
41        return ("timeout", 3600, "Spam: repeated messages")
42    return None
43
44def do_timeout(user_id, seconds):
45    expiry = (datetime.now(timezone.utc) + timedelta(seconds=seconds)).isoformat()
46    r = requests.patch(f"{BASE}/guilds/{GUILD_ID}/members/{user_id}",
47                       headers=H, json={"communication_disabled_until": expiry})
48    return r.status_code == 200
49
50def log_action(user_id, action, reason):
51    requests.post(f"{BASE}/channels/{MOD_LOG}/messages", headers=H, json={
52        "embeds": [{"title": f"MOD: {action.upper()}", "color": 16711680,
53                    "fields": [{"name": "User", "value": f"<@{user_id}>", "inline": True},
54                                {"name": "Reason", "value": reason, "inline": False}]}]
55    })
56
57@client.event
58async def on_ready():
59    logging.info(f"Moderation bot ready: {client.user}")
60
61@client.event
62async def on_message(message: discord.Message):
63    if message.author.bot or not message.guild:
64        return
65    result = check_violation(message)
66    if not result:
67        return
68    action, duration, reason = result
69    if not circuit_breaker_ok():
70        logging.warning("Circuit breaker active — skipping action")
71        return
72    user_id = str(message.author.id)
73    try:
74        if action == "timeout":
75            success = do_timeout(user_id, duration)
76        elif action == "kick":
77            resp = requests.delete(f"{BASE}/guilds/{GUILD_ID}/members/{user_id}", headers=H)
78            success = resp.status_code == 204
79        elif action == "ban":
80            resp = requests.put(f"{BASE}/guilds/{GUILD_ID}/bans/{user_id}",
81                                headers=H, json={"delete_message_seconds": 3600})
82            success = resp.status_code == 204
83        else:
84            success = False
85        if success:
86            action_times.append(time.time())
87            log_action(user_id, action, reason)
88            logging.info(f"{action.upper()} applied to {message.author.name}: {reason}")
89    except Exception as e:
90        logging.error(f"Moderation error: {e}")
91
92client.run(BOT_TOKEN)
93

Error handling

Rate Limits for Discord API

1import time, random
2
3def mod_action_with_backoff(method, url, headers, body=None, max_retries=3):
4    import requests
5    for i in range(max_retries):
6        resp = requests.request(method, url, headers=headers, json=body)
7        if resp.status_code == 429:
8            data = resp.json()
9            if data.get('global'):
10                print('Global rate limit — pausing all calls')
11            wait = data.get('retry_after', 1) + random.uniform(0, 0.5)
12            time.sleep(wait)
13            continue
14        return resp
15    raise RuntimeError('Max retries exceeded')

• Implement a circuit breaker: pause automated moderation after 20 actions per minute to avoid the 10,000 invalid request Cloudflare threshold during raids.
• Read X-RateLimit-Remaining on every moderation response and back off when it approaches 0 — moderation buckets refill every few seconds.
• Log every 429 response to your mod-log channel so human moderators know automated systems are under pressure.
• Check X-RateLimit-Global before deciding whether to pause only the current endpoint or all API calls.
• Consider using Discord's built-in AutoMod API (POST /guilds/{id}/auto-moderation/rules) for common patterns — it runs server-side and doesn't count against your API quota.

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

Best practices

• Start conservative: timeout-only for all violations, review logs for a week before enabling kicks or bans.
• Implement progressive escalation stored in a database — first violation gets a 1-hour timeout, second gets 24 hours, third gets a ban.
• Never auto-moderate the guild owner — they are immune to all bot actions. Always check if the target is the guild owner before attempting any action.
• Build a manual override command (/modstop) that disables automated actions and alerts human mods to take over.
• Separate spam detection (message rate, identical content) from content filtering (banned words) — they have different false positive profiles and may need different severity levels.
• Test moderation rules in a private test server with fake spam accounts before deploying to a real community.
• Implement the circuit breaker pattern: pause all automated actions after 20 actions per minute to protect against the 10,000 invalid request Cloudflare threshold.

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations

Explore related guides

Guides from other topics that help with this issue