Reference

How Honeypot Operates

Follow what the bot does from the moment something happens in Discord to the final action. A simplified, high-level view — not every check and edge case is shown.

Events

On Message

Message Received
In a honeypot channel?
No
End
(ignored)
Yes
Is this a bot-authored message?
Yes
End
(ignored)
No
Optional processing (runs for up to 2 seconds)
DM the user
(if not disabled)
Forward message to log channel
(if enabled)
Timeout for 1hr
(if enabled)
React to the message
(if ensure msg delete off)
Delete the message
(if ensure msg delete on)
Owner or admin?
Yes
End
(warning logged)
No
What to do?
SoftbanBan
Softbanned
(ban → unban)
Banned
Action succeeded?
No
Log what happened with a troubleshoot button
(even without a log channel)
Yes
Report the outcome
Update the warning message
(for new count)
Send log message
(if log channel set)
Queue followup cleanup
(for ensure msg delete)
Record the moderation
(for stats)
End

Good to know

  • Messages from slash commands are attributed to the person who ran them, so they are checked the same way as normal messages.
  • The DM, forwarded message and timeout run together in a short window before the action — they can be enabled individually.
  • The bot needs Ban Members and a role above the target's highest role. The server owner and admins are skipped and logged instead.
  • If the ban fails, the log message gets a button that can try to investigate possible reasons.

On Server Join

Bot added
Find or create the #honeypot channel
Post the warning message
Send a welcome message
after 2.5min
Delete the welcome message
Run setup health checks
(a few checks for perms)
Problems found?
Yes
Warn admin in the honeypot channel
(with the details)
No
Success?
YesNo
End
Asked to run /honeypot to setup

Server removal

Bot removed from server
Delete all saved settings
Clear cached server data
Stop counting the server
End

Channel delete

Channel deleted
Remove honeypot channel entry
Remove log channel entry
Drop channel-specific stats
(server total stays)
End

Message delete

Message deleted
Remove the saved message entry
Stop trying to update it
End

Good to know

  • The bot tries to clear out anything it no longer needs whenever the thing it belongs to is removed — see the privacy policy for the full details on how data is handled.

Cron

Jobs that run on their own — every day, or shortly after a moderation.

On Schedule

Scheduled run
(each day for servers)
Recreate channel
Get current channel
Make new channel
(with same config)
Transfer config
(if creation was successful)
Send warning message
(if enabled)
Delete old channel
(if creation was successful)
Channel warmer
Send keep alive message
Delete the message
Random channel name
Rename channel
(curated list or random chars for chaos mode)
Success?
YesNo
End
Warning posted in log channel
(if configured)

Good to know

  • Only servers with an experiment enabled run it, and the daily work is spread out so each server is handled once — see experiments.

On Followup

2 minutes after a moderation
Ensure Message Deletion on?
No
End
(ignored)
Yes
Search for leftover messages from the user
Delete them
End

Interactions

What happens when someone runs a command or clicks a button. The setup guide covers the user-facing side of these in more detail.

/honeypot

/honeypot invoked
Manage Server permission?
No
End
(reply with error)
Yes
Open configuration modal
(prefilled with current config)
Await modal submit
Permissions check out?
No
Reply with the issues
(no settings changed)
Yes
Quality checks
Ensure the warning message exists
Create an invite
(if reinvite on)
Set up webhooks
(if warmer on)
Try out newly enabled experiments
Channel warmer
Random channel name
Save config & reply with changes
End

/honeypot-messages

/honeypot-messages invoked
Manage Server permission?
No
End
(reply with error)
Yes
Honeypot set up?
No
End
(tell them to run /honeypot)
Yes
Open messages modal
(prefilled with existing messages)
Await modal submit
Check the messages
(bad words, user mention)
Validation passed?
No
Reply with validation error
(no changes saved)
Yes
Save changes
Update the warning message
End
(with reply & preview buttons)

/stats

Command in bot DMs
Fetch global stats
Fetch your moderation count
Reply with explainer + stats
End

Warning message button

Counter button pressed
Fetch global stats
Fetch this server's counts
Reply with explainer + stats
End

Unban button

Unban button clicked
Ban Members permission?
(you and the bot)
No
End
(reply with error)
Yes
Under 24 hours old?
No
End
(button expired)
Yes
Unban the user
Reply in the log channel
End

Troubleshoot button

Troubleshoot button clicked
Ban Members permission?
No
End
(reply with error)
Yes
Check why the ban failed
Bot has Ban Members?
User has Admin?
Compare role hierarchy
Reply with diagnostics
End
(ephemeral reply)

These charts simplify the real logic and leave out many checks and edge cases. For the complete behavior, read the source on GitHub.