Documentation

Complete reference for Honeypot — from adding the bot to a server to self-hosting your own instance with a custom web dashboard.

Introduction

Honeypot is a passive spam-bot detection system for Discord. Instead of using keyword filters, rate limits, or CAPTCHA challenges — which all have significant false-positive rates — it uses a fundamentally different approach: a trap channel.

The idea is borrowed from cybersecurity. In networking, a "honeypot" is a system intentionally left vulnerable to attract attackers — when something touches it, you know it's malicious, because nothing legitimate would go near it. Honeypot applies this exact principle to Discord channels.

The trap channel (#honeypot) is visible to everyone, but has @everyone Send Messages permission denied. The bot's role is the only one that can write there. The channel contains a visible warning message telling human members not to write in it. Real users read and comply. Automated spam bots don't — they scan every visible channel and blast their message into all of them without reading a word.

The moment a bot sends a message there, its nature is revealed with zero ambiguity. There is no need to analyse content or check account age — the action of sending a message in that channel is the proof.

How it works

The full detection and response flow, step by step:

The bot does not need to scan message content, check invite links, or look at account age. The trap channel is a binary signal: if you sent a message there, you're automated.

Prerequisites

Before adding Honeypot to your server, make sure of the following:

• You have Manage Server or Administrator permission on the server.
• The server has at least one channel visible to @everyone (so the bot can be seen).
• You can assign the bot's role to a position above regular member roles.

Quick start

From zero to a protected server in under two minutes:

/honeypot

Opens an interactive configuration panel. Only members with Manage Server or Administrator permission can run this command.

After submitting:

• Config is saved to data/config.json atomically (no corruption risk on crash).
• The warning message in the honeypot channel is edited in-place with the new settings.
• If you changed the honeypot channel, the old warning message is deleted and a new one is sent.
• The interaction reply is ephemeral — only you can see the confirmation.

/honeypot-messages

Opens a Discord modal to customise the three messages the bot sends. Requires Manage Server.

Leave any field blank to reset it to its default. Changes apply immediately — the warning message in the honeypot channel is edited in-place.

Example DM message

Hi {{user:mention}},

You were automatically {{action:text}} from **{{server:name}}** because your account
sent a message in our honeypot channel ({{honeypot:channel:link}}).

If your account was compromised, please:
1. Change your Discord password immediately
2. Enable two-factor authentication
3. Request an unban in our support server

Account created: {{user:created}}
Joined server: {{member:joined}}

Template variables

Template variables are placeholders replaced with live values when the bot sends messages. They work in the warning, DM, and log messages. Variables are case-sensitive and must use exactly double curly braces.

Actions

Three actions are available. The default is Softban, which covers most use cases without permanently locking out potentially-recovered accounts.

Regardless of the action setting, the bot always:

• Deletes the trigger message immediately (before anyone else can see it).
• Increments the kick counter on the warning message embed.
• Pushes a live stats update to the web dashboard.
• Attempts to DM the user (silently skipped if DMs are disabled).
• Posts a log entry if a log channel is configured.

Role hierarchy

Discord enforces a strict role hierarchy: you can only moderate users whose highest role is below your own. This rule applies to bots too. If the Honeypot role is position 3 and a user has a role at position 4, the bot cannot ban them.

How to fix it

1. Open Server Settings → Roles.
2. Find the Honeypot role in the list.
3. Drag it as high as possible — below your own admin/moderator roles, but above everyone else.
4. Save changes.

A good placement looks like this (higher = more powerful):

Permissions

The following permissions are requested during the invite flow. Each one has a specific purpose — the bot will not work correctly without them.

• Ban Members Required to execute softban and ban actions. Without this, the bot detects the trigger but cannot remove the user — it will send a warning message instead.
• Manage Messages Used to delete the trigger message immediately after it is sent. This prevents the spam content from being visible to other members, even briefly.
• Manage Channels Needed on first join to create the #honeypot channel with the correct permission overrides (@everyone can view but not send).
• Read Message History Allows the bot to fetch the existing warning message by its saved ID, so it can edit the kick counter in-place rather than sending a new message every time.
• Send Messages Required to post the warning message inside the honeypot channel, log entries in the log channel, and error messages when the bot cannot act.
• View Channels Basic visibility — required to read MessageCreate events in the honeypot channel.

Troubleshooting

FAQ

Can a real user accidentally trigger the honeypot?

Yes, in theory — if they read the warning message in the channel and still send a message, or if they don't notice the channel name and warning. In practice it's extremely rare with a well-named channel and a clear warning message.

If it does happen: with Softban, the user can rejoin immediately via any invite link. With Ban, you'll need to go to Server Settings → Bans and manually unban them. This is one reason Softban is the default.

Why not just use a verification bot?

Verification bots (CAPTCHA, reaction roles, etc.) add friction for all new members — including legitimate ones. Honeypot adds zero friction to real users and only catches bots in the act. The two approaches are complementary: use both for maximum coverage.

What about bots that don't send messages?

Honeypot only catches bots that send messages. It doesn't detect lurkers, selfbots that only read, or bots that use other attack vectors (inviting to external servers, DM spam, etc.). It's one layer of defence, not a complete solution.

Can I use the same honeypot channel for multiple purposes?

Technically yes, but it's not recommended. Any message triggers the action, so even a bot with legitimate access to your server could trigger it if it writes there. Keep the channel exclusively for the trap.

Does the bot see the content of trigger messages?

The bot receives the full message object (it needs it to delete the message), but it doesn't log or store message content anywhere. Only the user ID, action, and timestamps are saved.

How does the kick counter work?

The counter is per-server and increments on every successful moderation action. It's displayed on the warning message embed inside the honeypot channel as a button ("Kicks: N"). Clicking the button shows an ephemeral stats popup with the server total and a link to the web dashboard.

What is "Components V2" and why does it matter?

Components V2 is Discord's newer message composition system that allows structured layouts — containers, sections, separators, and thumbnails — rather than just embeds. Honeypot uses it for the warning message and stats popup to create a cleaner, more informative UI. It requires the IS_COMPONENTS_V2 message flag (1 << 15) to be set. Older Discord clients don't support it, but all current clients do.