Honeypot

Honeypot gives your server a trap channel that no real member should post in. Hacked accounts and spam bots post the same scam (a fake Steam gift, free Nitro, a crypto giveaway) in every channel they can reach, so they post in the trap too. When they do, your bot DMs them how to make their account safe, with an invite back, then softbans them: it bans them with their messages from the last hour deleted in every channel, then unbans them straight away. The scam is gone from every channel, and the real owner can rejoin once their account is safe.

Honeypot is free for every bot. There's no Premium part, and its runs, variables and stored values never count toward your free limits.

Before you start#

You need:

• Your bot in your Discord server. See Invite Your Bot if it isn't yet.
• Your bot's own role above your members' roles. A bot can't ban, kick or time out anyone whose highest role is above its own.
• A staff channel for the log, like #mod-log. In it, your bot needs View Channel, Send Messages and Embed Links.
• A trap channel, or let the bot make one. In it, your bot needs View Channel, Send Messages, Embed Links and Manage Messages.
• The Message Content intent turned on in the Discord Developer Portal, so the log can quote what they posted.

Each action and setting needs its own permission:

Setup#

1. 1

   Turn on Honeypot#

   Open Honeypot in your bot's dashboard and press Enable at the top right.

   

   • A Enable turns Honeypot on. It adds the events Honeypot needs and the custom variables it keeps its settings in. Honeypot has no commands.
   • B The server you're setting up. Every Honeypot setting belongs to one server (its trap channels, its roles and its log), so pick the server first. The page shows the server's icon and name on the settings you're changing.
   • C Reset to Default puts every setting in that server back to how a new Honeypot starts. The channels and roles stay.
   • D Docs opens this page.
2. 2

   Pick or create a trap channel#

   On the Traps tab, pick a channel in Trap channels, or press Create a trap channel for me. The bot makes #do-not-post-here at the top of your channel list and adds it to the trap channels.

   The buttons on the page use your saved settings, so press Save Changes after turning Honeypot on, before you press Create a trap channel for me.

3. 3

   Pick a log channel#

   On the Log tab, pick a staff channel in Log channel. Every catch goes there, with buttons for staff.

4. 4

   Save#

   A bar pops up at the bottom of the page. Press Save Changes. Your bot restarts to pick up the changes, which takes about 20 seconds.

   

5. 5

   Post the warning#

   On the Traps tab, press Post or update the warning. It tells real members to stay out of the trap. See The warning post.

   

   • A What to do next. Once everything is done, it says You're set.
   • B The steps, ticked off as you do them: Pick or create a trap channel, Pick a log channel and Post the warning. Press one to go to it.
6. 6

   Try it from an account that isn't staff#

   Post something in the trap from an account that isn't staff, like a friend's or a second account. With the settings Honeypot starts with, that account gets the DM, is softbanned, and the log shows the catch within a few seconds.

   Posting from your own account won't catch you: owners and staff are always skipped. You get a note in the channel and the sample DM instead, which is a good way to check the DM. See When staff post there.

The tabs#

Everything else is on five tabs. The preview on the right shows what members and staff see in Discord for the tab you're on.

• Traps: the trap channels, the warning post and the trap roles.
• Action: what happens to someone who's caught, the second sweep and giving roles back.
• Message them: the DM, the invite back and the sample staff get.
• Safety: who's skipped, staff posting in the trap, going easy on regulars and the surge pause.
• Log: the log channel, the log messages and the count.

Traps#

Trap channels#

Anyone who posts in a trap channel is caught.

• Trap channels: up to 5 text or announcement channels. Keep them visible and writable for everyone, near the top of the channel list. Don't call one honeypot.
• Create a trap channel for me: makes #do-not-post-here at the top of the channel list, with the topic "Don't post here. Spam bot trap: anyone who posts is removed." It adds the channel to the trap channels, then the page shows it. The channel gets no permission changes of its own, so it follows your server's @everyone permissions.

If a trap channel is deleted, or the bot can't see it any more, the page says Channel not found on its row, with a cross to take it out. Nothing is caught there.

The warning post#

The warning post goes in each trap channel, so real members know to stay out. It says the channel is a trap, that anything posted there gets the account removed, and to check their DMs for an invite back if they posted by mistake. Its last line shows how many spam accounts have been caught so far, kept up to date.

• Message: the post. Edit message opens the Message Builder.
• Post or update the warning: posts it in every trap channel. A post that's already there is edited where it is, so press it again after you change the message. If someone deletes the post, pressing it posts a new one.

Save before you post: posting uses your saved settings. Right after a save, the button waits for your bot to restart. Under the button, the page says whether the warning is in every trap channel, or which one it's missing from.

The count on the post is updated when someone is caught, at most once a minute, so a raid doesn't flood Discord with edits.

Trap roles#

Anyone who gets one of these roles is caught, the same way as posting in a trap channel.

• Catch members who get a trap role: on to start with. Nothing happens until you pick a role.
• Trap roles: up to 10. Staff who get one are skipped.

Add a trap role to Onboarding (in Server Settings) as an option no real person would pick. An account that picks every option gets the role and is caught before it can post anywhere. When their roles are given back later, the trap role is left out.

Action#

What happens to them#

• Action: what the bot does to someone who's caught.
  • Softban (to start with) removes them and deletes their messages, but they can rejoin once their account is safe.
  • Ban removes them for good and deletes their messages. Staff can unban them from the log.
  • Kick removes them. They can rejoin with an invite.
  • Timeout keeps them in the server but stops them talking for a while.
  • Give a role gives them a role you pick, like one that hides the rest of the server.
  • Only log: nothing happens to them. Staff see the log and decide.
• Delete their messages from: for Softban and Ban. Their messages in every channel, from this far back: 1 hour (to start with), 6 hours, 12 hours, 24 hours, 3 days or 7 days.
• Timeout for: for Timeout. From 1 minute to 28 days, Discord's longest. It starts at 24 hours.
• Role to give: for Give a role. The bot can only give roles below its own.

Only Softban and Ban delete their messages in other channels (that's Discord's rule). With Kick, Timeout, Give a role and Only log, only the message in the trap is deleted.

Whatever the action, their message in the trap is deleted first.

Sweep again#

• Sweep again after 2 minutes: on to start with, for Softban and Ban. Discord sometimes misses a message sent at the same moment as the ban. Two minutes later, the bot bans them by their ID again with the same delete window (and unbans them again after a softban), so anything left is deleted.

The sweep is skipped if they've already rejoined. Pressing Ban for good or Unban on the log in those two minutes stops it.

Give back roles#

Softban, Ban and Kick take their roles, because they leave the server. With the other actions they keep them. While either switch below is on, the bot keeps a note of their roles for 30 days so they can have them back.

• A Give back roles button on the log: on to start with. Staff press it once the member is safe. If they haven't rejoined yet, the roles come back when they do.
• Automatically when they rejoin: off to start with. Their account may not be safe yet, so leave this off unless you trust they've secured it.

With Ban, the log has only an Unban button, no Give back roles. The bot still keeps the note for 30 days: if you unban them, they get their roles back when they rejoin while Automatically when they rejoin is on.

Roles the bot can't give are never noted: @everyone, and roles Discord manages, like a bot's own role or the Server Booster role. The trap role they picked is left out too. If someone is caught again before their roles were given back, the first note is kept.

Message them#

Message them first#

• Send them a DM first: on to start with. It says how to make their account safe. It's sent before they're removed, while the bot still shares a server with them. If their DMs are closed, the bot carries on and the log says DMs closed.

The DM#

The DM says what happened to them in the server, that their account posted in a channel nobody is meant to use, and that someone else has probably got into their account. Then it lists the steps to make the account safe:

1. Change your password. That logs the other person out.
2. Turn on two-factor authentication.
3. In Settings, Authorized Apps, remove any you don't know.
4. Run a virus scan. Scam links often install a token stealer.

It links to Discord's guide to a hacked account, adds the invite back when there is one, and ends with "Replies to this bot aren't read."

The heading changes with the action: You were removed from (Softban and Kick), You were banned from, You were timed out in, Your access was limited in (Give a role) or Your message was deleted in (Only log), then the server's name. That's {hp_dm_title}.

• Message: the DM. Edit message opens the Message Builder. If you change it, keep {hp_invite_line} in it, or the invite back won't show.

Invite back#

• Add an invite back: on to start with. A one-use invite in the DM, so they can rejoin once their account is safe. It's only for Softban and Kick: a ban keeps them out, and the other actions leave them in the server.
• Invite to: the channel they land in when they rejoin. Leave it empty to use the first trap channel. Picking a welcome or rules channel is better (see the common questions).
• Works for: 1 to 7 days, Discord's longest. It starts at 7.

The invite goes out in the DM, so it's only made while Message them first is on.

The sample staff get#

When staff post in the trap or get a trap role, nothing happens to them, but they get this DM: the same DM a member would get, with "This is a sample. You're staff, so nothing happened." at the top. Its last line says members also get a one-use invite back.

• Message: the sample. Edit message opens the Message Builder.

Safety#

Who's skipped#

Staff are never caught. The server owner and anyone with Administrator, Manage Server, Manage Messages, Ban Members or Kick Members are always skipped.

• More roles to skip: members with any of these roles are treated like staff. They can also press the log's buttons.

When staff post there#

When staff post in a trap channel, their message is deleted, they get the sample DM, and the log says so. Use it to test.

• Show a note: on to start with. A note in the trap channel, deleted after 15 seconds.
• The note staff see: the note. It starts as "you're staff, so nothing happened. A member would have been softbanned. Check your DMs to see what they'd get."

Go easy on regulars#

• Go easy on regulars: off to start with, because a trap is a channel nobody should speak in. While it's on, a member who's been in the server at least the number of days you pick, and whose message has some text but no link, picture or @everyone, only has the message deleted. A hacked regular posting a scam link is still caught.
• Here for at least: 1 to 3,650 days. It starts at 30.
• The note regulars see: posted in the trap channel and deleted after 30 seconds. It starts as "this channel is a trap for spam bots, so your message was deleted. You've been here a while, so nothing else happened."

Links here are anything starting with http: or https:, and Discord invites. @here counts like @everyone. A message with no text (a forward, a sticker, or any message when your bot doesn't have the Message Content intent) is never treated as harmless, so it's caught.

Surge#

When several accounts are caught at once, the bot pauses invites and DMs and tells staff.

• Pause on a surge: on to start with. Discord pauses invites and DMs for the whole server, so a raid can't bring more in.
• Catches: how many accounts make a surge, from 2 to 50. It starts at 3.
• Within: from 1 to 60 minutes. It starts at 10.
• Pause for: from 1 to 24 hours, Discord's longest. It starts at 2.
• Role to ping: leave it empty to ping nobody.
• When a surge pauses invites: the alert, posted in the log channel with a Resume invites button. It goes once for each window.

The minutes are counted in fixed blocks of time (10:00 to 10:10, then 10:10 to 10:20, with 10 minutes), so catches either side of the change don't add up.

Log#

Log channel#

• Log channel: a staff channel for every catch, with buttons for staff. The bot needs to see it, send messages and embed links there. Surge alerts go here too.

With no log channel, catches still happen; nothing is logged.

The log messages#

Each log message has its own card on the Log tab:

• When someone is caught: what was done and to who ("Softbanned @kev"), where they posted or which trap role they picked, when their account was made and when they joined, their message as a quote (the first 500 characters), what else happened, their ID and the catch number. The "what else happened" line reads like "Messages from the last hour deleted · DM sent · invite sent · second sweep in 2 minutes".
• When it fails: the bot couldn't act, with the reason and what to change, like the bot's role being below theirs or a missing permission.
• When a regular posts: a regular's message was only deleted, while Go easy on regulars is on.
• When staff post: staff tried the trap or got a trap role.
• When roles come back: someone who was caught rejoined and got their roles back. It starts as "Roles given back" with "@kev rejoined and got their roles back." and their ID.

The log post gets buttons for staff, depending on the action:

• Ban for good: bans them by their ID, even if they've left, and forgets their saved roles.
• Unban: lifts the ban.
• Remove timeout: takes the timeout off.
• Give back roles: gives back the roles they had when they were caught. If they haven't rejoined yet, the bot says "They haven't rejoined yet. Their roles come back when they do." and gives them back when they rejoin.

After a press, the log post says who did what, like Banned for good by @Vez, and its buttons go. Anyone with Administrator, Manage Server or Ban Members, or a role in More roles to skip, can press them. Anyone else is told "You need Ban Members to do that." The buttons keep working for a year.

If a softban's ban worked but the unban didn't, they're still banned: the failure log says so and has an Unban button. When the ban itself failed, there's nobody to unban, so the failure log has no button.

Caught so far#

How many accounts were caught in the server. It's the count on the warning post, and every catch counts.

• Reset count: press it twice to put the count back to 0. The warning post shows it the next time someone is caught.

What happens when someone is caught#

1. A spam account posts "Free Nitro, claim here" in a trap channel. Their message is deleted.
2. The bot DMs them how to make their account safe, with a one-use invite back.
3. They're softbanned: banned with their messages from the last hour deleted in every channel, then unbanned.
4. The log channel gets the catch, with Ban for good and Give back roles. The count on the warning post goes up.
5. Two minutes later the second sweep deletes anything the first one missed.
6. If they post again in that minute, the message is only deleted: one catch per member a minute, however many messages.

Staff who post there aren't caught. Their message is deleted, they get a note and the sample DM, and the log says so.

The bot's messages#

Every message Honeypot sends has its own card on the tab it belongs to. Each card has the message, Edit message to open the Message Builder, and the variables it fills in (Fills in).

The DMs are sent as DMs. If their DMs are closed, the bot carries on.

Mentions in these messages never ping anyone, with two exceptions: the notes in the trap channel ping the member they're for, and the surge alert pings the role you pick in Role to ping.

Events#

Honeypot is made of ordinary builder blocks. Open an event to see how it works, or add your own blocks.

• Message Sent checks every message the bot can see. Only one check runs unless the message is in a trap channel. There, the message is deleted; staff get the note, the sample DM and a log line; a regular is let off while Go easy on regulars is on; and anyone else is caught. Other bots, webhooks and Discord's own system messages (like "joined the server") never count.
• Trap Role runs when a member gets a role. When it's one of the trap roles, staff get the sample DM and a log line, and anyone else is caught.
• Catch does the catch: it saves their roles, counts it, makes the invite back, DMs them, then does the action, the log post with its buttons, the warning posts' count, the second sweep and the surge pause. It also holds what the log's buttons do.
• Set Up runs from the page: Create a trap channel for me, Post or update the warning and Reset count.
• Rejoin runs when someone who was caught comes back. It gives their roles back while Automatically when they rejoin is on, or when a moderator pressed Give back roles before they rejoined.
• Bot Left deletes the count, the warning posts' IDs, the locks, the saved roles and the surge counts Honeypot kept for a server when your bot leaves it. The page's settings for it are kept.

Open in builder opens an event in the Command Builder, and the switch turns it on or off. Show variable names shows the variable behind each setting on the page, if you want to use them in your own commands. {BGVAR_honeypot_state.caught} is the count, if you want to show it somewhere else.

You can add blocks to any of them, like a ping in your mod channel at the end of Catch. Catch is a When triggered by a block event, so your own blocks can run it too, with member, place (the trap channel or role), kind (channel or role) and text (their message).

Message variables#

Each message card lists the variables its message fills in.

Every limit#

Every feature is free for every bot. On free bots, the log, the notes and the surge alert sometimes have a small Made with BotGhost line under them, about one time in three. The DM and the warning post never do, and Premium bots never do. Honeypot's runs, variables and stored values never count toward your free limits.

What Honeypot keeps#

• The count for each server.
• The ID of the warning post in each trap channel, so it can be edited.
• A one minute lock on each member who's being caught.
• Their roles when they were caught, while either Give back roles switch is on. They're forgotten once given back, when someone presses Ban for good, or after 30 days.
• The surge counts, forgotten after two windows.

Their message is never stored: it's only in the log post. When your bot leaves a server, everything Honeypot kept for it is deleted. The page's settings for it are kept.

Good to know#

• Each server has its own settings: trap channels, roles, the log and every message. Pick the server at the top of the page before you change them.
• A catch takes a few seconds from the post to the log.
• Without the Message Content intent, the log says the message had no text, and Go easy on regulars never lets anyone off.
• After an update to Honeypot, the page shows an Update button. Your own changes to the events and messages are kept.

Common questions#

A real member was caught by mistake. How do I undo it?

Their messages from the delete window can't be brought back, but the rest can be undone from the log post:

• Softban or Kick: they got the DM with an invite back. Press Give back roles on the log. If they haven't rejoined yet, their roles come back when they do.
• Ban: press Unban, then send them an invite.
• Timeout: press Remove timeout.
• Give a role: take the role off them in Discord.

If members keep posting there by mistake, check the warning post is in the channel, or turn on Go easy on regulars.

Someone posted in the trap and nothing happened

Check your bot is online, Honeypot is on, you saved, and the channel is in Trap channels for that server. Check the Message Sent and Catch events are switched on. If you posted yourself, you're staff: you get a note and the sample DM, and nothing else happens. Try from an account without Administrator, Manage Server, Manage Messages, Ban Members, Kick Members or a role in More roles to skip.

The log says it couldn't softban them

Your bot's role must be above the member's highest role, with Ban Members turned on. Drag your bot's role above your member roles in Server Settings > Roles. The log's reason says what Discord refused. For Kick, Timeout and Give a role, the bot needs Kick Members, Timeout Members or Manage Roles instead.

Their DMs are closed

The bot carries on with the action, and the log says DMs closed. They don't get the steps or the invite back. If it was a real member, a moderator can send them an invite once their account is safe.

How do trap roles work with Onboarding?

In Server Settings > Onboarding, add a question with an option that gives one of your trap roles and that no real person would pick. Spam accounts that pick every option get the role, and Honeypot catches them straight away, before they post anywhere. Turn on Catch members who get a trap role and pick the role on the Traps tab. Staff who get it are skipped.

Why must the trap channel stay visible and writable?

Hacked accounts and spam scripts post wherever they can. A trap channel they can't see, or can't post in, never catches anyone. Keep it near the top of the channel list too, since many scripts post in the first channels they find. The warning post tells real members to stay out.

Why shouldn't I call it honeypot?

A name like honeypot or trap tells a spammer what the channel is, and they skip it. A plain name like do-not-post-here works, with the warning post saying why.

Why did the invite back land them in the trap channel?

An invite has to point at a channel. When Invite to is empty, the bot uses the first trap channel, so someone who rejoins lands right in the trap. The warning post tells them not to post there. Pick a welcome or rules channel in Invite to on the Message them tab so they land somewhere safe.

Invites to my server are paused

A surge paused them: enough accounts were caught within your window. Press Resume invites on the alert in the log channel, or wait: they come back on their own after the time in Pause for. To stop it happening, turn off Pause on a surge or raise Catches on the Safety tab.