CodminBot - User Manual

Quick Start

1. Add the bot to your Telegram group
2. Make the bot an administrator with permissions:

• Delete messages
• Restrict members (ban/mute)
• Read all messages

1. Use /set_log_group to configure a logging group
2. Open/close group chat when needed with /open and /close
3. Start using moderation commands!

All commands available for admins and owner.

If non-admin send any bot command, message deletes and attempt writes in log-group (if log-group set).

Commands

Basic Moderation

/ban [user1] [user2] ... [reason]

Ban one or multiple users from the group permanently.

Note: When using /ban by replying to a message, the original message (including media: photos, videos, GIFs, stickers, documents, etc.) is fully quoted in the log group.

Usage:

• Reply to user's message: /ban or /ban reason[optional]
• Single user: /ban @username reason[optional] or /ban 123456789 reason[optional]
• Multiple users: /ban @user1 @user2 @user3 reason[optional] or /ban 123456789 987654321 reason[optional]
• Mixed format: /ban @user1 123456789 @user2 reason[optional]

Examples:

• /ban (when replying to a message)
• /ban @spammer Violating rules
• /ban 123456789 Spam
• /ban @spammer1 @spammer2 @spammer3 All spamming
• /ban @user1 123456789 987654321 Multiple violations

/unban [user]

Unban a previously banned user.

Usage:

• Reply to user's message: /unban
• By username: /unban @username
• By user ID: /unban 123456789

/mute [user1] [user2] ... [duration] [reason]

Temporarily or permanently mute one or multiple users (prevent them from sending messages).

• Supergroups: full mute via restrictions (temporary/permanent).
• Regular groups: Telegram API does not support temporary mute; the bot logs the attempt to the log group and does not kick/mute the user.

Note: When using /mute by replying to a message, the original message (including media: photos, videos, GIFs, stickers, documents, etc.) is fully quoted in the log group.

Duration formats:

• 10m or 10min - 10 minutes
• 2h or 2hour - 2 hours
• 1d or 1day - 1 day
• forever, 0, inf, permanent, perm - permanent mute (no expiration)
• without specifying the duration, users will be muted for 1 day (default)

Usage:

• Single user (reply): /mute (default: 1 day) or /mute 10m reason
• Single user: /mute @user 2h Spamming or /mute 123456789 1d Violating rules
• Multiple users: /mute @user1 @user2 @user3 2h Spamming or /mute @user1 123456789 1d Violations
• Multiple users with reason: /mute @user1 @user2 10m All spamming
• Permanent mute: /mute @user forever or /mute @user1 @user2 0 Spam bots

Examples:

• /mute (when replying to a message, default: 1 day)
• /mute 10m (when replying, mute for 10 minutes)
• /mute @user 2h Spamming
• /mute 123456789 1d Violating rules
• /mute @user1 @user2 @user3 1d All spamming
• /mute @user forever (permanent mute)
• /mute @user1 123456789 0 Spam bots (permanent mute for multiple users)

/unmute [user]

Remove mute restrictions from a user.

• Supergroups: via restrict_chat_member with open permissions.
• Regular groups: via unban_chat_member (no error message to main chat on failures).

Usage:

• Reply to user's message: /unmute
• By username: /unmute @username
• By user ID: /unmute 123456789

/warn [user] [reason] [-s|-save] [-n|-notify]

Issue a warning to a user.

• In supergroups: after 3 warnings (configurable) the user is auto-muted for the configured duration.
• In regular groups: warnings are counted, but auto-mute is not applied (Telegram API limitation); a notification is shown instead.
• Note: When using /warn by replying to a message, the original message (including media: photos, videos, GIFs, stickers, documents, etc.) is fully quoted in the log group.
• By default the offending message is deleted when you reply with /warn, and bot's notification is auto-deleted. Flags (must be among first two arguments, can be used simultaneously): -s/-save — save the offending message; -n/-notify — keep bot's notification in chat.

Usage:

• /warn (when replying to a message)
• /warn @user Spam
• /warn 123456789 Violating rules
• /warn -s (reply to save the offending message)
• /warn -n (keep bot's notification in chat)
• /warn -s -n or /warn -n -s (save both offending message and bot's notification)

/delete [message] [reason] [-s|-save] [-n|-notify]

Delete a message. Flags (must be among first two arguments, can be used simultaneously): -s/-save — save the target message; -n/-notify — keep bot's notification in chat.

Usage:

• Reply to message: /delete or /delete reason text
• Keep bot notification: /delete -n reason text
• Save target message and keep bot notification: /delete -s -n reason text or /delete -n -s reason text

Configuration

/open and /close (chat access control)

Open or close the group for member messages.

• Primary short commands: /open, /close
• Full aliases (same behavior): /open_chat, /close_chat, /open_group, /close_group
• Only group admins/owner can use these commands.
• Works only in group/supergroup chats.
• Bot applies chat permissions and sends one status message:
• on state change: "group opened/closed by admin command"
• if state is unchanged: "group already open/closed"

Usage:

• /open
• /close
• /open_group
• /close_chat

/set_log_group [group_id]

Set a group for logging all bot actions.

Usage:

• /set_log_group -1001234567890

Note: Only group administrators can use this command.

Join Request Auto-Review

CodminBot can automatically verify join requests with short, randomized challenges. This reduces manual review for admins and keeps the group protected from spam accounts. The feature is disabled by default and must be enabled per group. It is available only on Advanced and Pro plans (including the first-month Advanced trial). On Free plan, join request auto-review controls are locked and admins are prompted to upgrade on the website.

How it works

1. A user sends a join request.
2. If auto-review is enabled, the bot sends a private challenge in the user’s language (fallback to English).
3. The user must answer within the configured time and attempt limit.
4. The bot approves or declines the request and logs the result in the log group.

Challenge types

• Math sum
• Emoji repeat
• Emoji count
• Multiple choice (accepts equivalent A/B/C letters across alphabets, case, and common lookalikes)
• Word echo (type the shown word)

Enable or configure per group

1. Open the bot menu → My groups
2. Select your group
3. Tap Join request checks
4. Toggle auto-review and choose which checks are enabled

Audit log

The log group receives: status, method, attempts, user language, and user profile flags (if available).

Note: If the bot is removed from the log group or loses send permissions, the log group configuration is cleared automatically. After restoring access, run /set_log_group again.

Service Message Auto-Cleanup

CodminBot automatically removes noisy Telegram service messages (when the bot has can_delete_messages):

• member joined / member left
• group title changed
• group photo added/removed
• pinned message updates
• group/supergroup migration notices
• auto-delete timer changes
• video chat service events (scheduled/started/ended/invites)

Each deletion can be mirrored to the log group with safe Markdown escaping (including usernames/links with underscores).

Shortcuts (Pro Plan Only)

• /b - Shortcut for /ban
• /ub - Shortcut for /unban
• /m - Shortcut for /mute
• /um - Shortcut for /unmute
• /w - Shortcut for /warn
• /d or /del - Shortcut for /delete

Subscription Plans

Payment may be disabled on some deployments. Manage subscriptions in the "My groups" menu or on the website.

Free Plan

• Basic moderation commands: /ban, /unban, /mute, /unmute, /open, /close
• 3 actions per day for ban & mute, 5 actions per day for unban & unmute
• User IDs are masked in logs
• Promotion messages after 30 days
• Join request auto-review is not available

Advanced Plan

• All Free plan features
• + /warn command
• + /delete command
• No promotion messages
• User IDs stay masked in logs
• No daily action limits
• Join request auto-review (with multilingual anti-confusion answer normalization)

Pro Plan

• All Advanced plan features
• Unlimited actions per day
• Shortcut commands (/b, /ub, /m, /um, /w, /d, /del)
• Full user IDs visible in logs
• LLM spam detection and AI features
• No promotion messages

FAQ

Q: How do I set up the bot?

A: Add the bot to your group, make it an administrator, and use /set_log_group to configure logging.

Q: Why can't I use some commands?

A: Some commands are only available on paid plans. Check your subscription plan in the "My groups" menu.

Q: What happens when daily limit is reached?

A: You'll receive a notification. Upgrade your plan in the "My groups" menu or on the website to remove daily limits.

Q: How do warnings work?

A: Users receive warnings for rule violations. In supergroups, after 3 warnings (default), they are automatically muted for 24 hours. In regular groups the counter grows, but auto-mute is not applied (Telegram limitation).

Q: Can I customize warning limits?

A: Currently, the default is 3 warnings. Customization will be available in the web dashboard (coming soon).

Troubleshooting

Bot doesn't respond to commands

• Check that the bot is an administrator
• Verify the bot has necessary permissions (read & write messages in the managing group)
• Ensure you're using commands in a group (not private chat)
• If the log group is not configured, the bot will show a warning in the chat, but it is throttled and may appear only occasionally

Commands not working

• Make sure you're a group administrator or owner
• Check that the bot has required permissions
• Verify your subscription plan allows the command

Logging not working

• Use /set_log_group to configure a logging group
• Ensure the bot is added to the logging group
• Check that the logging group ID is correct
• If the bot was removed or restricted in the log group, the configuration is cleared automatically; re-run /set_log_group after fixing permissions

Users not found when banning/muting

• Users must have sent at least one message in the group to be in the bot's database
• If a user hasn't sent messages, use Telegram's built-in ban/mute feature instead
• All errors (users not found, failed operations) are logged to the log group for reference

Mute not working in regular groups

• The bot automatically handles both regular groups and supergroups
• For regular groups, the bot uses a different method that works correctly
• If you encounter issues, check the log group for detailed error messages

Support

For issues or questions:

• Telegram: https://t.me/codminbot_support
• Website: https://codmin.bot

Scheduled pinning (/pin, /delete_pin, /unpin)

• /pin supports reply-to-message or a group message link (https://t.me/c/{group_id}/{message_id}).
• Command parses flexible argument order: link, HH:MM, and optional date (dd.mm, dd/mm/yyyy, 1 feb, 1 february, etc.).
• If date+time are omitted, pin happens immediately.
• If only time is provided and it is already in the past, bot asks to include date.
• Queue is persisted in DB table pin_schedules and restored via background executor, so pins survive restarts/network outages.
• Repeating /pin for the same message updates the existing scheduled time.
• /delete_pin <message_link> removes an entry from scheduled queue.
• /unpin unpins immediately (reply or link) and validates that the target is currently pinned.
• All planned and executed pin actions are mirrored to the log group.
• Command and bot responses are auto-deleted with configurable delay (DELETE_NOTIFICATION_DELAY, default 10 sec).