SudoBot Per-Guild Configuration Reference (config.json)

SudoBot stores per-guild settings in a JSON file at $SUDO_PREFIX/config/config.json. Each top-level key in that file is a Discord guild ID, and the value is the configuration object for that guild. You can edit the file directly while the bot is offline, or use the bot’s configuration commands to update it at runtime.

All time values in the guild configuration are in milliseconds unless otherwise stated. For example, a two-hour mute duration is 7200000.

File structure

config.json

{
  "GUILD_ID": {
    "prefix": "-",
    "debug_mode": false,
    "commands": { ... },
    "permissions": { ... },
    "infractions": { ... },
    "antispam": { ... },
    "logging": { ... }
  }
}

Replace GUILD_ID with the Discord snowflake ID of your server. You can add multiple guilds by adding additional top-level keys.

Top-level fields

prefix

string

default:"-"

The command prefix used for legacy text commands. Set this to any string, such as ! or ?.

debug_mode

boolean

default:"false"

Enables extra debug logging for this guild. Useful when diagnosing configuration problems. Turn this off in production.

Commands

The commands object controls how the bot handles command invocations in this guild.

config.json

{
  "GUILD_ID": {
    "commands": {
      "mention_prefix": true,
      "moderation_command_behavior": "default",
      "rerun_on_edit": false,
      "channels": {
        "list": [],
        "mode": "exclude"
      },
      "disabled_commands": [],
      "respond_on_precondition_fail": true,
      "ratelimiting": {
        "enabled": true,
        "timeframe": 7000,
        "max_attempts": 5,
        "block_duration": 1000
      },
      "troll_command_immune_users": []
    }
  }
}

commands.mention_prefix

boolean

default:"true"

When true, users can invoke commands by mentioning the bot instead of using the text prefix (e.g., @SudoBot ban).

commands.moderation_command_behavior

string

default:"default"

Controls what happens to the command message after a moderation command runs. Set to "delete" to automatically delete the invoking message, or "default" to leave it.

commands.rerun_on_edit

boolean

default:"false"

When true, the bot re-executes a command if the user edits their original command message.

commands.channels.list

array of snowflakes

default:"[]"

List of channel IDs that the channels.mode rule applies to.

commands.channels.mode

string

default:"exclude"

Set to "exclude" to block commands in the listed channels, or "include" to allow commands only in the listed channels.

commands.disabled_commands

array of strings

default:"[]"

Names of commands that are disabled in this guild. Users who try to run these commands receive no response.

commands.respond_on_precondition_fail

boolean

default:"true"

When true, the bot sends an error message when a command’s preconditions are not met (e.g., missing permissions). Set to false to silently ignore such invocations.

commands.ratelimiting.enabled

boolean

default:"true"

Enables per-user command rate limiting for this guild.

commands.ratelimiting.timeframe

integer

default:"7000"

The sliding window duration in milliseconds within which max_attempts commands are allowed.

commands.ratelimiting.max_attempts

integer

default:"5"

Maximum number of commands a user can run within timeframe milliseconds before being rate-limited.

commands.ratelimiting.block_duration

integer

default:"1000"

How long in milliseconds the user is blocked after exceeding the rate limit.

commands.ratelimiting.overrides

object

Per-command rate limit overrides. Keys are command names; values have the same shape as the top-level ratelimiting object. Use this to apply stricter limits to sensitive commands.

commands.troll_command_immune_users

array of snowflakes

default:"[]"

User IDs who are immune to troll commands (commands that perform harmless pranks on members).

Permissions

config.json

{
  "GUILD_ID": {
    "permissions": {
      "mode": "discord",
      "check_discord_permissions": "always",
      "invincible": {
        "roles": [],
        "users": []
      }
    }
  }
}

permissions.mode

string

default:"discord"

Selects the permission system. Accepted values:

"discord" — uses Discord’s built-in role permissions
"levels" — uses SudoBot’s numeric permission level system
"layered" — combines both systems

permissions.check_discord_permissions

string

default:"always"

Controls when Discord’s native permission checks are applied. Accepted values: "always", "during_automod", "during_manual_actions", "never".

permissions.command_permission_mode

string

Overrides the system-level command_permission_mode for this guild. Accepted values: "ignore", "overwrite", "check".

permissions.invincible.roles

array of snowflakes

default:"[]"

Role IDs whose members cannot be targeted by moderation actions, even by other moderators.

permissions.invincible.users

array of snowflakes

default:"[]"

User IDs that cannot be targeted by moderation actions.

Invincible roles and users bypass moderation commands entirely. Be careful about which roles you mark as invincible, as moderators will not be able to act on those members.

Infractions

config.json

{
  "GUILD_ID": {
    "infractions": {
      "send_ids_to_user": false,
      "dm_fallback": "none",
      "reason_templates": {},
      "reason_template_placeholder_wrapper": "{{%name%}}",
      "points": {
        "warning": 1,
        "mute": 3,
        "timeout": 3,
        "kick": 5,
        "ban": 10,
        "tempban": 8,
        "softban": 7
      }
    }
  }
}

infractions.send_ids_to_user

boolean

default:"false"

When true, the DM sent to an infracted user includes the infraction ID so they can reference it when appealing.

infractions.dm_fallback

string

default:"none"

What to do when the bot cannot DM the user. Accepted values:

"none" — do nothing
"create_channel" — create a temporary channel and post the infraction message there
"create_thread" — create a temporary thread instead

infractions.dm_fallback_parent_channel

snowflake

The channel ID in which the fallback channel or thread is created. Required when dm_fallback is not "none".

infractions.dm_fallback_channel_expires_in

integer

default:"604800000"

How long the fallback channel or thread remains open before the bot deletes it. Default is one week (604800000 ms).

infractions.reason_templates

object

default:"{}"

Named reason templates. Keys must match [A-Za-z0-9_-]+. Values are the full reason text. Reference them in commands using the placeholder wrapper.

infractions.reason_template_placeholder_wrapper

string

default:"\\{\\{%name%\\}\\}"

The syntax used to insert a reason template into a command. The default {{%name%}} means you would type {{%warn_toxicity%}} in a command to expand the warn_toxicity template.

infractions.points

object

Infraction point values assigned to each action type. These accumulate on a member’s record and can trigger automatic escalations. All default to sensible values; set any to 0 to make that action point-neutral.

Anti-spam

config.json

{
  "GUILD_ID": {
    "antispam": {
      "enabled": false,
      "limit": 5,
      "timeframe": 3000,
      "channels": {
        "list": [],
        "mode": "exclude"
      },
      "actions": [
        { "type": "delete_message" },
        { "type": "warn", "reason": "Spam detected" }
      ]
    }
  }
}

antispam.enabled

boolean

default:"false"

Enables the anti-spam system for this guild.

antispam.limit

integer

required

Maximum number of messages a user can send within timeframe milliseconds before being flagged as spam.

antispam.timeframe

integer

required

The time window in milliseconds for counting messages toward the spam limit.

antispam.channels.list

array of snowflakes

default:"[]"

Channel IDs that channels.mode applies to.

antispam.channels.mode

string

default:"exclude"

"exclude" to disable anti-spam in listed channels, or "include" to enable it only in those channels.

antispam.actions

array of moderation actions

The moderation actions to apply when spam is detected. Each action object must have a type field. Supported types: ban, kick, mute, role, warn, verbal_warn, clear, delete_message, none.

Logging

config.json

{
  "GUILD_ID": {
    "logging": {
      "enabled": false,
      "bulk_delete_send_json": true,
      "global_ignored_channels": [],
      "default_enabled": true,
      "primary_channel": "LOG_CHANNEL_ID",
      "hooks": {},
      "overrides": [],
      "exclusions": [],
      "unsubscribed_events": []
    }
  }
}

logging.enabled

boolean

default:"false"

Enables the logging system for this guild.

logging.primary_channel

snowflake

The channel ID where the bot sends all log events that don’t have a specific channel override.

logging.bulk_delete_send_json

boolean

default:"true"

When true, bulk message deletions are logged as a JSON attachment containing all deleted messages.

logging.default_enabled

boolean

default:"true"

When true, all log event types are enabled by default even if no override is configured for them.

logging.global_ignored_channels

array of snowflakes

default:"[]"

Events from these channel IDs are never logged, regardless of overrides.

logging.hooks

object

default:"{}"

Maps message IDs to channel IDs for special webhook-based logging. Keys and values are both snowflakes.

logging.overrides

array

Per-event-type channel routing rules. Each entry specifies an array of events and either enables them with a target channel or disables them.

config.json

{
  "overrides": [
    {
      "enabled": true,
      "events": ["message_delete", "message_update"],
      "channel": "CHANNEL_ID"
    },
    {
      "enabled": false,
      "events": ["member_ban_add"]
    }
  ]
}

logging.exclusions

array

Rules that exclude specific users, channels, or category channels from logging. Each exclusion specifies a type ("user", "channel", or "category_channel"), a list of snowflakes, a mode ("exclude" or "include"), and an optional list of events to apply the exclusion to.

logging.unsubscribed_events

array of strings

default:"[]"

Event types that the bot never logs, even if default_enabled is true. Use this to opt out of specific noisy events without configuring full overrides.

AI auto-moderation

config.json

{
  "GUILD_ID": {
    "ai_automod": {
      "enabled": false,
      "max_total_score": 10,
      "max_single_score": 7,
      "actions": [
        { "type": "delete_message" }
      ]
    }
  }
}

ai_automod.enabled

boolean

default:"false"

Enables AI-powered auto-moderation using Google’s Perspective API. Requires PERSPECTIVE_API_TOKEN to be set in your environment.

ai_automod.max_total_score

integer

default:"10"

The maximum allowed combined score across all toxicity categories before an action is triggered. Scores are on a 0–10 scale.

ai_automod.max_single_score

integer

default:"7"

The maximum score any single toxicity category (e.g., toxicity, insult, threat) may reach before an action is triggered.

ai_automod.max_individual_scores

object

Per-category score thresholds. Categories include: toxicity, threat, severe_toxicity, identity_attack, insult, profanity, sexually_explicit, flirtation, spam, obscene, incoherent, unsubstantial. All default to 7.

ai_automod.actions

array of moderation actions

default:"[]"

Actions to apply when a message exceeds the score thresholds.

ai_automod.exception_regex_patterns

array

default:"[]"

Regular expressions that exempt matching messages from AI moderation. Each entry is either a pattern string or a [pattern, flags] tuple.

ai_automod.evaluate_after_attempts

integer

default:"-1"

How many messages from a user to skip before starting AI evaluation. Set to -1 to evaluate every message.

ai_automod.automatic_actions

object

Configures automatic escalation tiers based on accumulated scores. stops maps score thresholds to action arrays.

Raid protection

config.json

{
  "GUILD_ID": {
    "raid_protection": {
      "enabled": false,
      "threshold": 10,
      "timeframe": 60000,
      "action": "auto",
      "member_actions": [],
      "send_log": true,
      "channels": [],
      "channel_mode": "exclude"
    }
  }
}

raid_protection.enabled

boolean

default:"false"

Enables raid detection for this guild.

raid_protection.threshold

integer

default:"10"

Number of members joining within timeframe milliseconds that triggers the raid response.

raid_protection.timeframe

integer

default:"60000"

The time window in milliseconds used to count join events.

raid_protection.action

string

default:"auto"

What the bot does when a raid is detected. Accepted values:

"auto" — lets the bot choose the most appropriate response
"lock" — locks all channels
"antijoin" — enables anti-join mode, kicking or banning new arrivals
"lock_and_antijoin" — does both
"none" — logs the raid but takes no action

raid_protection.member_actions

array of moderation actions

default:"[]"

Actions applied to each member who joins during an active raid.

raid_protection.send_log

boolean

default:"true"

When true, the bot sends a log message when a raid is detected.

Member verification

config.json

{
  "GUILD_ID": {
    "member_verification": {
      "enabled": false,
      "vpn_proxy_check_enabled": true,
      "conditions": {
        "age_less_than": 604800,
        "no_avatar": false,
        "always": false
      },
      "unverified_roles": [],
      "verified_roles": [],
      "method": "dm_interaction",
      "max_duration": 3600
    }
  }
}

member_verification.enabled

boolean

default:"false"

Enables the member verification gate for this guild.

member_verification.vpn_proxy_check_enabled

boolean

default:"true"

When true, the bot uses ProxyCheck.io to detect VPN and proxy connections during verification. Requires PROXYCHECKIO_API_KEY.

member_verification.conditions.age_less_than

integer

Require verification for accounts younger than this many seconds.

member_verification.conditions.no_avatar

boolean

Require verification for accounts with no avatar.

member_verification.conditions.always

boolean

default:"false"

When true, every new member must verify regardless of their account age or avatar status.

member_verification.unverified_roles

array of snowflakes

default:"[]"

Roles assigned to members who have not yet verified. Remove these roles from verified members automatically.

member_verification.verified_roles

array of snowflakes

default:"[]"

Roles granted to members once they complete verification.

member_verification.method

string

default:"dm_interaction"

How the verification challenge is delivered. Accepted values:

"dm_interaction" — sends the challenge via DM
"channel_interaction" — posts the challenge in a channel
"channel_static_interaction" — posts a persistent challenge message in a channel

member_verification.max_duration

integer

Maximum time in seconds a member has to complete verification before expired actions are applied.

Welcomer

config.json

{
  "GUILD_ID": {
    "welcomer": {
      "enabled": false,
      "channel": "CHANNEL_ID",
      "custom_message": "Welcome, {{user}}!",
      "mention": true,
      "randomize": false,
      "force_embeds": true,
      "delete_after": 30000,
      "say_hi_button": {
        "enabled": true,
        "label": "Say Hi",
        "emoji": "👋",
        "reply": ":acc: said hi to you!",
        "expire_after": 300000
      }
    }
  }
}

welcomer.enabled

boolean

default:"false"

Enables welcome messages for this guild.

welcomer.channel

snowflake

required

The channel ID where welcome messages are posted.

welcomer.custom_message

string

The welcome message text. Leave unset to use the default message.

welcomer.mention

boolean

default:"false"

When true, the welcome message mentions the new member.

welcomer.randomize

boolean

default:"false"

When true, the bot randomly picks from a set of built-in welcome messages instead of using custom_message.

welcomer.force_embeds

boolean

default:"true"

Forces welcome messages to use embed formatting.

welcomer.forced_embed_color

integer

The embed color as a decimal integer (e.g., 5793266 for #587BF2). Only applies when force_embeds is true.

welcomer.delete_after

integer

Automatically deletes the welcome message after this many milliseconds.

welcomer.say_hi_button.enabled

boolean

default:"false"

Adds a “Say Hi” button to the welcome message that other members can click to greet the new arrival.

welcomer.say_hi_button.expire_after

integer

default:"300000"

How long the button remains clickable in milliseconds. Minimum 5000, maximum 600000 (10 minutes).

Auto-role

config.json

{
  "GUILD_ID": {
    "auto_role": {
      "enabled": false,
      "roles": ["ROLE_ID"],
      "ignore_bots": true
    }
  }
}

auto_role.enabled

boolean

default:"false"

Automatically assigns roles to new members when they join.

auto_role.roles

array of snowflakes

default:"[]"

Role IDs to assign automatically.

auto_role.ignore_bots

boolean

default:"true"

When true, auto-role does not apply to bot accounts.

Reaction roles

config.json

{
  "GUILD_ID": {
    "reaction_roles": {
      "enabled": false,
      "ignore_bots": true,
      "ratelimiting": {
        "enabled": true,
        "timeframe": 7000,
        "max_attempts": 5,
        "block_duration": 10000
      }
    }
  }
}

reaction_roles.enabled

boolean

default:"false"

Enables the reaction roles feature for this guild.

reaction_roles.ignore_bots

boolean

default:"true"

When true, bot reactions do not trigger role assignment.

reaction_roles.ratelimiting

object

Rate limits reaction role assignments to prevent abuse. Has the same fields as command rate limiting: enabled, timeframe, max_attempts, and block_duration.

Bump reminder

config.json

{
  "GUILD_ID": {
    "bump_reminder": {
      "enabled": true,
      "remind_after": 7200000,
      "reminder_content": "Time to bump! Use /bump",
      "on_bump_content": "Thanks for bumping! I'll remind you in 2 hours."
    }
  }
}

bump_reminder.enabled

boolean

Enables the bump reminder for this guild. Reminds members to use /bump after the cooldown expires.

bump_reminder.disabled_channels

array of snowflakes

default:"[]"

Channels where the bump reminder is never sent.

bump_reminder.remind_after

integer

default:"7200000"

How long to wait after a bump before sending the reminder. Default is two hours.

bump_reminder.reminder_content

string

The message sent when it is time to bump again.

bump_reminder.on_bump_content

string

The message sent immediately after a successful bump.

Message reporting

config.json

{
  "GUILD_ID": {
    "message_reporting": {
      "enabled": false,
      "logging_channel": "CHANNEL_ID",
      "users": [],
      "roles": [],
      "permissions": []
    }
  }
}

message_reporting.enabled

boolean

default:"false"

Enables the message reporting feature, allowing members to flag messages for moderator review.

message_reporting.logging_channel

snowflake

The channel where reported messages are sent for review.

message_reporting.users

array of snowflakes

default:"[]"

User IDs who can submit reports.

message_reporting.roles

array of snowflakes

default:"[]"

Role IDs whose members can submit reports.

message_reporting.permissions

array of strings

default:"[]"

Discord permission names (e.g., "ManageMessages") required to submit reports.

Additional features

Anti-member join

Prevents new members from joining by automatically kicking or banning them. Use this during an active raid as an alternative to full lockdown.

config.json

{
  "GUILD_ID": {
    "anti_member_join": {
      "enabled": false,
      "behavior": "kick",
      "custom_reason": "Server is temporarily locked.",
      "ban_duration": 3600000,
      "ignore_bots": false
    }
  }
}

Set behavior to "kick" or "ban". If "ban", set ban_duration to automatically lift the ban after the specified milliseconds.

Quick mute

Adds quick-mute buttons to messages so moderators can mute a member with a single click.

config.json

{
  "GUILD_ID": {
    "quick_mute": {
      "enabled": false,
      "mute_emoji": "🔇",
      "mute_clear_emoji": "🧹",
      "default_duration": 7200000,
      "reason": "Quick mute applied by moderator"
    }
  }
}

Channel archives

Moves inactive channels into an archive category automatically.

config.json

{
  "GUILD_ID": {
    "channel_archives": {
      "enabled": false,
      "archive_category": "CATEGORY_ID",
      "ignored_channels": []
    }
  }
}

Echoing

Controls whether the echo command can produce messages with mentions.

config.json

{
  "GUILD_ID": {
    "echoing": {
      "allow_mentions": true
    }
  }
}

Muting role

Specifies the role used for muting members when Discord timeouts are unavailable.

config.json

{
  "GUILD_ID": {
    "muting": {
      "role": "MUTE_ROLE_ID"
    }
  }
}

You can add a $schema field pointing to the auto-generated JSON schema file to get editor autocompletion. SudoBot generates the schema at $SUDO_PREFIX/config/schema/config.schema.json on startup (unless NO_GENERATE_CONFIG_SCHEMA is set).

Get Started

Configuration

Moderation

Features

Extensions

SudoBot Per-Guild Configuration Reference (config.json)

File structure

Top-level fields

Commands

Permissions

Infractions

Anti-spam

Logging

AI auto-moderation

Raid protection

Member verification

Welcomer

Auto-role

Reaction roles

Bump reminder

Message reporting

Additional features

Build docs developers (and LLMs) love

Get Started

Configuration

Moderation

Features

Extensions

Documentation Index

​File structure

​Top-level fields

​Commands

​Permissions

​Infractions

​Anti-spam

​Logging

​AI auto-moderation

​Raid protection

​Member verification

​Welcomer

​Auto-role

​Reaction roles

​Bump reminder

​Message reporting

​Additional features

Build docs developers (and LLMs) love

File structure

Top-level fields

Commands

Permissions

Infractions

Anti-spam

Logging

AI auto-moderation

Raid protection

Member verification

Welcomer

Auto-role

Reaction roles

Bump reminder

Message reporting

Additional features