Captcha Verification

Why Captcha Matters for Telegram Groups

Telegram groups are frequent targets for automated bot accounts that join, post spam links, and leave before any admin can react. Traditional moderation tools only work after the damage is done — the spam message is already visible to your members. Captcha verification flips this model by challenging every new member at the door, before they can post anything. If the new member is a real person, they solve a simple challenge and are granted full posting access. If it is an automated bot, it fails the challenge and is removed from the group automatically.

The entry gate system coordinates captcha with other gates like force subscribe and rules acceptance. When a new member joins, the bot immediately mutes them and presents the first active gate. Only after all gates are cleared does the bot unmute the member and send the welcome message. This ensures that no spammer can post during the verification window, even if they somehow solve the captcha quickly.

Four Captcha Types for Different Needs

BotWave offers four distinct captcha types, each suited to different community requirements. The button captcha is the simplest — new members see a button labeled "I am human" and must tap it within the timeout period. This is effective against simple bots that cannot interact with inline buttons, though sophisticated bots may eventually bypass it. The math captcha presents a basic arithmetic problem (like "What is 7 + 3?") that the user must solve, filtering out bots that cannot parse and answer mathematical questions.

The text captcha asks the user to type a randomly generated string, similar to traditional web captchas. This is harder for bots to defeat because it requires optical character recognition or manual configuration. The AI Guardian captcha is the most advanced option — it generates a unique question with multiple-choice answers using artificial intelligence, so every new member faces a different challenge that cannot be pre-programmed into a bot. The AI Guardian is particularly effective against determined attackers who might otherwise reverse-engineer a fixed captcha format.

Configurable Failure Actions

When a new member fails the captcha challenge, the bot needs to take action. You can configure what that action is: kick the user (they can rejoin and try again), ban them permanently (they cannot return), or mute them indefinitely (they stay in the group but cannot post). The kick option is the most lenient and is suitable for communities that want to give genuine users a second chance if they simply made a mistake. The ban option is for groups under active attack where you want to permanently remove failed verifications.

The retry limit controls how many attempts a user gets before the failure action triggers. A higher limit is friendlier to real users who might misread a captcha, while a limit of one is stricter and more effective against bots that try multiple times. The timeout setting determines how long the user has to complete the challenge — too short and real users may not have time to read and respond, too long and bots have more time to attempt automated solutions.

Rules Acceptance Gate

When captcha is enabled, you can optionally add a rules acceptance gate. After the user solves the captcha, they are presented with the group rules and a button to accept them. Only when they tap the accept button are they fully unmuted and allowed to participate. This ensures that every new member has at least seen the rules, reducing the "I did not know that was not allowed" excuse for rule violations.

The rules acceptance gate is particularly valuable for larger communities where enforcing rules consistently is a challenge. By making acceptance a condition of entry, you create a clear record that the user was informed of the rules before they started posting. If they later violate a rule, the warning or ban carries more weight because they explicitly accepted the rules upon joining.

Entry Gate Coordination

The captcha system does not operate in isolation. It is part of the entry gate framework that coordinates multiple verification steps in sequence. When a new member joins, the bot evaluates which gates are active — force subscribe, captcha, rules acceptance, and join confirmation — and runs them in a configurable order. The bot mutes the new member at the start and only unmutes them when every gate is cleared.

If the bot lacks restrict permissions in the group, it detects this and skips the muting step rather than leaving the user stuck in a muted state indefinitely. This graceful degradation ensures that the gates still function as informational barriers even when the bot does not have full admin rights. The gate order can be customized through the captcha configuration settings, letting you decide whether force subscribe comes before or after captcha, for example.

Available Commands