How to build a Telegram captcha bot to stop group spam
By the Botable team
A Telegram captcha bot verifies new members before they can post. It restricts each joiner, asks for one tap or a simple answer, and unrestricts whoever passes. Describe the challenge and the timeout, and Botable builds it.
What is a captcha bot?
A Telegram captcha bot is the cheapest spam filter a group can have, because the overwhelming majority of spam accounts join and post without ever interacting with a button. The flow is short: on join, restrict the member so they cannot send messages, post a challenge naming them, and lift the restriction when they pass. What makes or breaks it is the failure path — a member who never answers has to be removed on a timer, or the group fills with permanently muted ghosts and the member count stops meaning anything. Two details matter more than the challenge itself. The challenge message must be deleted after it resolves, or the chat becomes a wall of verification prompts; and the bot needs the restrict-members permission, without which every part of this silently does nothing.
What commands does it have?
| Command | What it does |
|---|---|
on join | Restricts the member and posts a challenge |
tap to verify | Unrestricts a member who passes |
/captcha button|math | Switches the challenge type |
/timeout 120 | Seconds before an unverified member is removed |
/unverified | Lists members who have not passed |
What do you need before you start?
- A Telegram bot token from @BotFather
- The bot promoted to admin in the group, with restrict-members permission
- A timeout you are comfortable with — long enough for a real person on a phone
How do you build it?
What kind of challenge actually works?
A single button is enough for automated spam and costs a real person one tap. A small arithmetic question or an emoji match raises the bar against semi-automated accounts at the cost of some legitimate drop-off. Start with the button; escalate only if spam gets through.
What happens to someone who never answers?
They get removed when the timer expires — that is the part people forget to ask for. Say whether removal is a kick (they can rejoin and try again) or a ban (they cannot). A kick is almost always right; a real person who missed the prompt deserves a second attempt.
How do you keep the chat clean?
Delete the challenge message once it is resolved, and the join notice with it. Ask for this explicitly. A busy group without cleanup accumulates one or two dead messages per join, which is more visible noise than the spam you were filtering.
Why would the bot do nothing at all?
Almost always missing admin rights. Restricting and removing members both require the bot to be an admin with the restrict-members permission; without it Telegram rejects the action and the join proceeds normally. Check this first before changing anything else.
A prompt you can use as-is
Paste this into Botable and adjust the details. It is specific on purpose — a vague description produces a vague bot.
Build a captcha bot for my group. When someone joins, restrict them from sending messages and post a message that mentions them with a single "I'm not a robot" button. When they tap it, unrestrict them and delete both the challenge and the join notice. If they have not tapped within 120 seconds, remove them from the group — a kick, not a ban, so they can rejoin. /captcha switches between button and simple-math challenges, /timeout sets the seconds, /unverified lists anyone still pending.
Who is this bot for?
- Public groups that appear in Telegram search and get joined by bots daily
- Communities that grew past the point where a human can watch every join
- Any group where spam arrives faster than moderators wake up
What goes wrong with this kind of bot?
- Without restrict-members permission every action fails silently — check admin rights first
- No timeout means muted ghosts accumulate forever and the member count becomes fiction
- Challenges harder than one tap cost you real members; escalate only when spam proves it necessary
Questions about captcha bots
Does this replace a moderation bot?
No, it complements one. A captcha filters the join; a moderation bot handles what happens afterwards — link filtering, warnings, mutes. Most groups eventually want both, and one bot can do both if you describe them together.
Will it annoy legitimate members?
One tap, once, on joining is close to invisible. The annoyance comes from harsh timeouts and multi-step challenges. Keep the timeout generous — two minutes, not twenty seconds — because people join and then put their phone down.