Docs and FAQ – VoidSentry

Set up in three steps

A trap channel is a channel nobody has a reason to write in. Self-bots and hijacked accounts post in every channel they can reach, so the first message in the trap gives them away and VoidSentry bans the account at once. Normal members never see a reason to write there.

Let VoidSentry ban. Add the bot, then in Server Settings → Roles give its role the Ban Members permission and drag the role above the roles it should ban (see role position).
Add a trap channel. Create a channel such as #do-not-post and run /setup-trap in it, or add it from the dashboard. The bot posts a warning in the channel.
Choose a log channel. Use /add-logchannel or the dashboard. Pick a private moderator channel: every ban is reported there with an Unban button, and so is every ban the bot could not carry out.

Until all three are done the dashboard shows a checklist. Want to see it work before it bans anyone? Turn on dry-run first.

Permissions

The invite link asks for these. Each one has a job:

Ban Members – the whole point. Without it the bot can only report.
View Channels and Read Message History – to see the trap channel and what was written in it.
Manage Messages – to remove the trapped message and, on a ban, the account's recent messages.
Send Messages, Embed Links and Attach Files – for the warning in the trap channel and the ban log, which is an embed with an image.

If you create a separate role for the bot, give it these permissions in the trap channel and the log channel too. A channel-level deny overrides a server-level allow.

Role position

Discord only lets a role ban members whose highest role is below its own. If the VoidSentry role sits under a role that the offending account has, the ban fails, however many permissions the bot has. In Server Settings → Roles, drag the VoidSentry role up until it is above every role a normal member or a spammer could hold. Nobody can ban the server owner, whatever the role order.

Dry-run

With dry-run on, VoidSentry reacts as usual but does not ban: it only posts to the log channel who it would have banned. Use it for a day or two after setup to confirm that only the people you expect write in the trap. Turn it off with /trap-settings or in the dashboard. Dry-run events are not stored, so they show up only in the log channel.

Who is never banned

Administrators, and members whose role is on the exempt roles list. Their message in a trap channel is removed, nothing more.
The server owner, and anyone the bot is not allowed to ban by Discord's role rules.

Before a ban the account gets a direct message explaining why, when its privacy settings allow it. The message text is kept as evidence for the retention period set by whoever hosts the bot (90 days by default), then cleared.

“It did not ban someone”

This is the most common question. Go through the list in order; the log channel usually says which one it was.

Is dry-run on? Then nobody is banned by design. Check /trap-settings view or the dashboard.
Was it really a trap channel? The channel has to be on the list. A channel you created but never ran /setup-trap in does nothing.
Is the person an administrator or in an exempt role? Then their message is removed without a ban. This catches moderators who test the trap.
Is the bot's role above theirs? See role position. A failed ban is reported in the log channel, and once a day the server owner gets a direct message about it.
Does the bot have Ban Members? The dashboard checklist shows this in step 1.
Can the bot see and delete in the channel? A channel permission override can hide the channel from the bot even though its role has the permission server-wide.
Is the bot online? Check the status page.

Still stuck? Open an issue with the server ID (never a token or a message you do not want public) and what you expected to happen.

Common errors

“Missing Permissions” in the log: The bot lacks Ban Members, or its role is below the account's highest role. Fix the role order first.
“Unknown Ban” when unbanning: The ban was already lifted. The dashboard treats this as success.
The log channel stays empty: The log channel is not set, or the bot cannot send messages or embed links there.
The dashboard does not list my server: You need Administrator (or to own the server), and the bot must be in it. Servers without the bot are listed with an invite link.
“Too many requests”: The dashboard limits how fast one person can search and export. Wait a minute.

Undoing a ban

Press Unban under the ban in the log channel, use /unban with the user ID, or open the ban in the dashboard's ban history and press Unban. Every unban is written to the server's change log. Unbanning does not delete the ban record; it stays in the history.

Data deletion requests

Someone who was banned can ask for the records about them to be deleted: open an issue on our GitHub page titled “Data request”, with the user ID. The privacy policy has the details. The owner deletes the records everywhere with /purge-user or on the dashboard's owner page. Deleting records does not lift any Discord ban; an administrator of each server does that with /unban.

Self-hosting

VoidSentry is open source. You can run your own copy, with or without the dashboard; the bot's README covers setup, backups and the dashboard API. The terms and privacy policy on this site describe the bot we host, not copies you run yourself.