Captcha Commands

Complete guide to Captcha module commands and features

🔐 Captcha Commands

Protect your group from bots and spammers with CAPTCHA verification!

Force new members to prove they’re human by solving a simple challenge before they can send messages.

Captcha Types: × Math: Solve simple arithmetic problems × Text: Identify text shown in an image

Admin Commands: × /captcha <on/off>: Enable or disable captcha verification × /captchamode <math/text>: Set captcha type (math problems or text recognition) × /captchajoin <on/off>: Verify join requests in private messages (default: off; no argument shows its state) × /captchatime <1-10>: Set timeout in minutes (default: 2) × /captchaaction <kick/ban/mute>: Set action for failed verification (default: kick) × /captchamaxattempts <1-10>: Set maximum verification attempts (default: 3)

When enabled, new members are automatically muted until they complete the captcha. If they fail or timeout, the configured action is taken.

How It Works:

1. When captcha is enabled, new members are automatically muted upon joining
2. A captcha challenge is sent to the new member
3. The user must select the correct answer from the provided options
4. If successful, the user is unmuted and can participate in the group
5. If they fail or timeout, the configured action is taken (kick, ban, or mute)

Captcha Types:

• Math: Solve simple arithmetic problems (addition, subtraction, multiplication)
• Text: Identify text shown in a distorted image

Pending Messages Feature: When a user is completing the captcha, any messages they try to send are stored and deleted. Admins can:

• View what messages a user tried to send using /captchapending
• Clear stored messages using /captchaclear

This helps identify potential spam attempts before users complete verification.

Join-request verification in PM

Use /captchajoin on for groups that require approval to join. This is independent of /captcha on: either check can be enabled on its own. /captchajoin shows the current state; /captchajoin off restores the existing auto-approval or admin-button flow. The /captcha status and /settings summary also show this setting.

• Applicants receive a private captcha naming the group. It uses /captchamode, /captchatime and /captchamaxattempts, with a 5-minute maximum timeout.
• A correct answer approves the request even when /autoapprove is off. Users on the group’s approved list are approved immediately without a challenge.
• Running out of time or attempts declines the request; /captchaaction does not apply. The applicant is not kicked, banned or muted for failing a join captcha.
• When /spamdb is enabled, its ban action bans and declines a listed applicant; mute declines them; log logs the match and still sends the challenge.
• If the bot cannot send the PM, it falls back to /autoapprove or the usual Approve / Decline / Ban buttons. A failed PM never declines the request.
• Admin buttons are shown only for that fallback. Captcha and spam-database outcomes are sent to the configured log channel.
• After approval, the normal welcome still appears. A recent successful join captcha skips the regular captcha, so the user does not solve it twice.

Telegram allows the bot to contact applicants for only five minutes, until their request is processed, and only if another admin has not already contacted them. The bot needs the Invite users permission to receive, approve and decline requests. Join-request verification does not require restricting members.

Available Commands

Usage Examples

Basic Usage

/captcha
/captchaaction
/captchaclear
/captchajoin on

For detailed command usage, refer to the commands table above.

Module Aliases

These are help-menu module names, not command aliases.

This module can be accessed using the following aliases:

• captcha

Required Permissions

Bot Requirements:

• Ban users (for kick/ban actions)
• Restrict members (for muting during verification)
• Delete messages (for cleaning up captcha messages)

Captcha Refresh:

• Available for image-based captchas (math image and text modes)
• Users can refresh up to 3 times with a 5-second cooldown between refreshes
• Refreshes generate a new captcha image without resetting the attempt counter

Orphaned Captcha Recovery: On bot restart, any pending captcha attempts are automatically processed:

• Expired attempts: failure action is applied (kick/ban/mute)
• Still-valid attempts: the existing challenge is retained and its remaining timeout is rescheduled
• Incomplete attempts that never received a Telegram message are removed and the user’s chat permissions are restored

Messages intercepted while verification is pending are deleted. After a successful answer, the bot sends a summary of their types and count; it does not replay their original contents.

Failure Actions:

• kick - Remove the user while allowing them to rejoin
• ban - Permanently ban the user
• mute - Keep the user muted for 24 hours