Sodium documentation
Sodium is an all-in-one bot for Discord: moderation, AI moderation, logging, tickets, a welcomer, giveaways, a message builder and analytics. Almost everything below is configured from the dashboard - a handful of moderation actions run as slash commands, and nothing here needs hosting or code.
Getting started #
Adding Sodium takes about two minutes. You need the Manage Server permission on the server you want to add it to.
- Open the dashboard and sign in with Discord.
- Servers where Sodium is already active appear first. Servers you can add it to appear under Add Sodium.
- Pick a server, accept the permission prompt, and Sodium joins instantly.
Sodium does nothing until you enable a system. Adding the bot is safe - no messages are scanned and no events are logged until you turn a feature on.
Permissions #
Sodium requests a focused set of permissions when you add it. Each maps to a system you can use:
| Permission | Used for |
|---|---|
Moderate Members | Timeouts issued by the moderation and AI systems. |
Kick / Ban Members | Kick, softban and ban actions and their cases. |
Manage Messages | Deleting flagged content and proof messages. |
View Audit Log | Attributing server events to the right actor in logs. |
Manage Webhooks | Posting clean, branded log embeds to your channels. |
Manage Channels / Manage Threads | Opening and closing ticket channels. |
Manage Roles | Toggling reaction roles from message buttons. |
Send Messages / Embed Links / Attach Files | Welcomer greetings, generated images, giveaway posts and message templates. |
Sodium can only act on members below its own highest role. Keep the Sodium role above the roles you want it to moderate.
The dashboard #
The dashboard is where every server is configured. After signing in you'll see two groups:
- Your Sodium servers - servers where the bot is already a member. Select
Configureto manage its systems. - Add Sodium - servers you manage where the bot isn't yet. Select
Inviteto add it to that exact server.
Only servers where you hold Manage Server or Administrator are shown - the same gate Discord uses for adding bots.
Fetching server data
Channel and role pickers in the workspace read from a saved snapshot of your server rather than calling Discord on every page load, which keeps the dashboard fast and avoids rate limits. If you've just created a channel or role and don't see it yet, press Fetch data at the top of the sidebar to pull a fresh copy. Refetching is limited to once every 30 seconds.
Moderation & cases #
Every moderation action is recorded as a numbered case with the moderator, target, reason, optional duration and up to two proof images.
Actions
Sodium supports warn, timeout, kick, softban and ban, each as a slash command your moderators run in Discord. Every command takes a reason, an optional duration and up to two proof images:
# time a member out for an hour with a reason
/mute user:@Nova reason:spamming in general duration:1hThe timeout command is /mute. Everything else about the system - per-action defaults, requiring a reason, deleting the offending message, immunity - is configured once per server, so your whole team stays consistent without memorizing flags.
Per-action defaults
Under Moderation → Action defaults each action - warn, timeout, kick and ban - carries its own settings. reason and duration on a command are optional: leave them out and the server's default is used, so /warn user:@Nova files the same reason every time without anyone typing it.
| Setting | Effect |
|---|---|
reason | Filed when the moderator gives no reason. Falls back to "No reason given". |
duration | Used by /mute when no duration is given. |
force_reason | Blocks the action until a reason is supplied - the default is not used. |
force_duration | Blocks a timeout until a duration is supplied. |
delete_proof_message | Removes the offending message once the case is filed. Applies where Sodium acted on a specific message - AI moderation and automod - since a slash command has no message attached. |
/softban follows the ban settings. Changes take effect within a minute.
Immunity
Protect staff from automated punishment by marking roles or individual users as immune in the dashboard. Immune targets are skipped by the manual, AI and automod paths alike.
| Setting | Effect |
|---|---|
immune_roles | Members with any listed role are never auto-punished. |
immune_users | Specific users are never auto-punished. |
AI moderation #
AI moderation scores content as it arrives and acts when your thresholds are crossed. It runs on three scan types, each toggled independently:
- text - message content for harassment, hate and other categories.
- image - attachments and embeds for NSFW and graphic content.
- scam - links and message patterns matching known scams.
Rules
You build rules under Moderation → AI moderation in the dashboard. A rule binds a category and a threshold (0–1 confidence) to an action - a higher threshold means the model has to be more certain before Sodium acts. For example, a rule can time out anyone whose message scores 0.80 or higher for harassment, or delete an image that scores 0.90 for graphic content. Each scan type keeps its own set of rules.
Start permissive. Set thresholds high (0.85+) and the action to warn, watch the logs for a few days, then tighten. Every AI action is filed as a case, so nothing is invisible.
Advanced automod #
Automod is twelve rule-based filters that watch every message. Unlike AI moderation there is no scoring - a filter either matches or it doesn't. Each one is toggled on its own card under Moderation → Advanced automod, and each carries its own scope, rules and actions.
Counting filters
Nine filters count something over a time frame. You add conditions that read as a sentence: when a user reaches at least or exactly N, within a window, run these actions. Set the time to 0 to check a single message instead of a window.
| Filter | Counts |
|---|---|
spam | Messages sent by the user. |
channel spam | Distinct channels the user posted in. |
mentions | User and role mentions. |
attachments | Images, videos and files. |
emojis | Custom and standard emojis. |
lines | Lines a message spans. |
capitalization | Percentage of letters in caps, ignoring very short messages. |
polls | Polls the user created. |
warns | Warn cases on the user, checked whenever a new warn is filed. |
Group filters
Words, links and invites use groups instead - a named list of entries with its own actions, so a slur list can ban while a mild list only deletes.
- words - words, phrases and regular expressions. Toggle whether capitalization matters and whether a whole word is required.
- links - domains to act on. A subdomain matches its parent domain unless you require a whole match.
- invites - acts on any Discord invite, except the server IDs and invite codes you list as allowed.
Scope
Every filter has its own Where it applies: roles and channels in either ignore these or only these mode. Ignoring a category ignores the channels inside it, and ignoring a channel ignores its threads. Immune roles and users are skipped by automod entirely, as they are everywhere else.
Actions
A condition or group with no actions detects but does nothing. Actions run in a fixed order so they can't undercut each other: reactions and roles first, then the DM, then the case actions (warn, timeout, kick, ban), then the report, and the message deletion last. Warns, timeouts, kicks and bans are filed as cases and routed to your moderation log channels, exactly like a manual command.
Counting filters wait out their own window before firing again, so one burst produces one punishment rather than one per message. Word, link and invite filters act on every matching message, so nothing slips through.
Logging #
Logging routes server events to channels you choose. Each of the eighteen event types can go to its own channel, so message logs and member logs never crowd each other.
Event types
messages · members · roles · channels · threads · voice · invites · webhooks · emojis · stickers · scheduled events · polls · automod · stage · soundboard · applications - and more.
Exemptions
Silence the noise you don't need. Exempt channels, roles or users from logging entirely:
| Exemption | Effect |
|---|---|
exempt channel | Events in that channel are never logged. |
exempt role | Actions by members with that role are skipped. |
exempt user | A specific user's events are skipped. |
Tickets #
Tickets let members open a private channel with your staff. They're tracked from the same dashboard as everything else, so support lives next to moderation instead of in a second bot.
- Members open a ticket from a panel button or select menu - you build the panel under Messages and post it to a channel from the dashboard.
- Sodium creates a private channel and pings your staff roles.
- Closing the ticket (or running
/ticket close) saves a transcript, then removes the channel.
Transcripts & ticket logs
When a ticket closes, Sodium renders the whole conversation - messages, embeds and attachments - into a styled HTML transcript that looks like the original chat. Open Tickets → Ticket logs in the dashboard to see recent open and closed tickets and to view or download any transcript.
Transcripts are kept for 14 days after a ticket closes, then deleted automatically. Download the ones you want to keep before they expire.
Welcomer #
The welcomer greets people as they arrive and marks the moments that matter. It sends a message on three events, each configured and toggled on its own:
- Welcome - when a member joins the server.
- Leave - when a member leaves or is removed.
- Boost - when a member boosts the server.
Message content
Each event can send plain text, an embed, a generated image, or any combination. Text and embed fields understand variables that are filled in per member when the message sends:
| Variable | Becomes |
|---|---|
{user} | The member's username, as plain text. |
{user.mention} | A ping of the member. |
{user.name} | The member's display name. |
{server} | The server name. |
{count} | The current member count. |
Dynamic images
Under Welcomer → Dynamic images you design a banner from layers - a background, text and the member's avatar - and attach it to any event. Sodium renders it fresh for each member, dropping in their avatar and name. Use Simulation to preview an event, and Send test to fire a real message to your channel with your own account.
Uploading your own images
Each dynamic image can hold two uploads of its own - PNG, JPEG, WebP or GIF up to 8MB each. Upload from the background panel or from an Uploaded image layer, then pick which upload that layer or background uses. A typical pairing is one upload as the background and one as a logo layer.
Uploads are processed the moment they arrive: every EXIF and metadata tag is stripped (orientation is applied first, so photos stay the right way up), anything larger than 1600px is scaled down, and the file is recompressed to WebP. Nothing about where a photo was taken survives the upload, and a multi-megabyte photo usually lands under 100KB.
| Limit | Free | Subscribed |
|---|---|---|
| Dynamic images per server | 5 | 20 |
| Uploads per dynamic image | 2 | 2 |
| Upload file size | 8MB | 8MB |
Deleting a dynamic image deletes its uploads with it. Removing an upload that a background or layer still points at leaves that layer empty rather than breaking the render, and duplicating an image copies the layout but not the uploads.
Giveaways #
Giveaways are prize draws members enter with a button. Sodium posts an embed to a channel, tracks entries, draws weighted winners when the clock runs out and announces them in the same channel. Switch Giveaways on in the dashboard first - until you do, /giveaway create refuses and no message counts are recorded.
Creating one
- From the dashboard under Giveaways - name the prize, then set the channel, winners, end time, requirements and boosters in the editor, with a live preview of the Discord message beside it.
- From Discord with
/giveaway create, which covers the common case in one go:
# three winners, entries open for two days
/giveaway create prize:Nitro Classic duration:2d winners:3Durations are written as 30m, 12h, 3d or 1w and can be combined (1d 12h). Anything from one minute to 180 days is accepted. Changes made in the dashboard and in Discord are the same giveaway - edit it from either side and the posted message updates within a few seconds.
Requirements
Requirements are checked the moment someone presses Enter giveaway. Anyone who doesn't qualify gets a private reply listing exactly what they're missing, and every requirement you set is also printed on the giveaway embed so nobody presses blind.
| Requirement | Effect |
|---|---|
required roles | Up to 10 roles, matched as any of or all of. |
blocked roles | Holding any of these roles blocks entry. |
messages sent | Messages the member has sent in your server since giveaways were enabled. |
members invited | Joins credited to invite links the member created. |
account age | Minimum age of the member's Discord account, in days. |
days in server | How long the member has been in your server, in days. |
Boosters
Booster roles hand out extra entries instead of gatekeeping. Give a role up to +50 entries and add up to six of them; a member holding two roles worth +2 and +1 enters with 4 entries, capped at 100 per member. Winners are drawn weighted by entries, so extra entries improve the odds without guaranteeing anything, and the same member is never drawn twice in one draw.
Drawing & rerolling
Sodium draws automatically at the end time, edits the message to show the winners and replies in the channel pinging them. You can also press Draw now to end early, or Reroll winners on a finished giveaway to draw a fresh set from everyone who entered - the same commands exist as /giveaway end and /giveaway reroll.
The public page
Every giveaway gets a shareable page at /giveaway/{server}/{giveaway} - the View online button on the message links to it. It shows the prize, a live countdown, entry count, requirements, boosters and the winners once drawn, and works for anyone with the link, signed in or not.
A server can have 25 running giveaways at once, each with up to 20 winners. Finished giveaways keep their entries and winners, so you can reroll later.
Leveling #
Leveling rewards members for taking part. They earn xp for chatting and, if you want it, for time spent in voice; xp turns into levels, and levels can hand out roles you choose. Switch Leveling on in the dashboard first - until you do, no xp is recorded and /rank and /leaderboard say so.
Earning xp
Every message earns a random amount of xp inside a range you set - 15 to 25 by default - but only once per cooldown. The cooldown defaults to 60 seconds, so a member who sends ten messages in a minute earns xp for one of them. This is what stops spam from buying levels; raise the cooldown to slow progression, lower it to speed it up.
| Setting | Default | Effect |
|---|---|---|
xp per message | 15 – 25 | A random amount in this range, once per cooldown. |
cooldown | 60s | Messages sent inside the window earn nothing. |
voice xp | off | Xp per minute spent in a voice channel. |
no xp channels | none | Channels where messages never earn xp. |
no xp roles | none | Roles whose members never earn xp. |
Turn Voice xp on to credit members for time in a voice channel - 5 xp a minute by default. Sodium checks every minute and skips anyone who is deafened, in an AFK channel, or sitting in a channel alone, so an idle connection doesn't farm levels.
The curve
Going from level n to the next level costs 5n² + 50n + 100 xp. Level 1 arrives at 100 xp, level 5 at 1,150, level 25 at 42,000 - each level costs more than the last, so early progress feels quick and high levels stay meaningful. The dashboard draws the curve so you can see the shape before you change the rates.
Level roles
Pair a level with a role and members get it the moment they reach that level. By default only the highest role a member has earned is kept, so the reward replaces the previous one as they climb; turn Stack level roles on to let them keep everything they've earned instead.
Free servers can set 5 level roles. Premium servers can set 50. Sodium needs the Manage Roles permission and its own role must sit above every role it hands out.
Level-up messages
When a member levels up Sodium posts a message. Leave the channel unset and it lands in whichever channel they were talking in, which keeps the celebration where the conversation is; pick a channel to send every level-up to one place instead. The message itself is yours to write:
| Variable | Resolves to |
|---|---|
{user} | The member's display name. |
{user.mention} | Mentions the member. |
{user.name} | The member's username. |
{level} | The level they just reached. |
{server} | The server name. |
Boosted xp
Multipliers raise how much xp is earned, and come in two kinds. A role multiplier applies whenever a member holds that role - handy for boosters or supporters. A scheduled multiplier applies to everyone during days and hours you pick, which is how you run a double-xp weekend. Times are UTC.
Multipliers stack: a member with a 2× role posting during a 2× window earns 4×. Free servers can set 3 multipliers, premium servers 25.
Leaderboard
Members can check themselves with /rank - it shows their level, rank, total xp and a progress bar to the next level - or see the top ten with /leaderboard. The dashboard shows the top 25 under Leveling → Leaderboard, where you can also reset every member's xp.
The same ranking is public at /leaderboard/{server} - a shareable page showing the top members, their levels and how far along each one is. It works for anyone with the link, signed in or not, and it only exists while leveling is switched on.
Messages #
Messages is a shared builder for rich embeds with buttons and dropdowns. You design a message once as a template, then reuse it wherever Sodium sends messages on your behalf.
- Ticket panels - the message members click to open a ticket. A button can open a ticket, a dropdown can offer several ticket types.
- Reaction roles - buttons that toggle a role on and off for whoever presses them.
- Sticky messages - a template that Sodium keeps pinned to the bottom of a channel, reposting it as the conversation scrolls.
Buttons carry an action - toggle a role, send another template, open a ticket, or link out. Templates share the same variables as the rest of Sodium, so {user.name}, {server} and {ticket.number} resolve when the message is sent.
Analytics #
Analytics shows how your server is doing over time - message and voice activity, membership growth, and where new members come from. It's on by default and needs no setup; numbers begin appearing within a minute of activity.
| Metric | What it tracks |
|---|---|
| Messages | Messages sent per text channel, per day. |
| Voice | Time spent and sessions per voice channel. |
| Membership | Joins, leaves and net growth. |
| Invites | How many joins each invite link brought in. |
Analytics only ever stores counts - never the content of anyone's messages. Daily totals are kept for 180 days, then dropped automatically.
Commands #
Sodium is configured almost entirely from the dashboard - these are the only slash commands, and each shows only to members with the matching Discord permission. Everything else (cases, immunity, AI rules, log routing, ticket panels, welcomer and analytics) lives in the dashboard.
| Command | Description |
|---|---|
/warn | Warn a member and open a case. |
/mute | Time a member out for a duration. |
/kick | Kick a member and open a case. |
/softban | Ban and immediately unban to purge recent messages. |
/ban | Ban a member and open a case. |
/ticket close | Close the current ticket and save a transcript. |
/ticket claim | Claim the current ticket for yourself. |
/giveaway create | Start a giveaway members enter with a button. |
/giveaway edit | Change the prize, winners, time left or channel of a running giveaway. |
/giveaway end | Close entries and draw the winners now. |
/giveaway reroll | Draw new winners for a finished giveaway. |
/rank | Show a member's level, rank and xp. |
/leaderboard | Show the top members by xp. |
/ping | Check bot and database latency. |
FAQ #
Is Sodium free?
Yes. Adding Sodium and using its core systems is free. Subscriptions unlock higher limits on some servers.
Does Sodium store my messages?
Almost never. Moderated content is scored in transit and discarded - only cases and the logs you configure are persisted. Analytics keeps counts (how many messages, not what they said) for 180 days, giveaways keep a per-member message count while they're enabled so message requirements can be checked, and leveling keeps a per-member xp total. The one exception is tickets: when a ticket closes, its conversation is saved as a transcript for 14 days so your staff can review it, then deleted automatically.
What happens if I remove Sodium?
All of that server's settings, cases and logs are deleted automatically. Re-adding starts clean.