Telegram moderation bots: avoid mistakes when deleting, muting, and banning

A moderation command should not jump from “this message is a problem” to “remove this person forever.” Deleting one message, restricting what a member can send, banning a member, and lifting a ban change different parts of a Telegram community. Their permission requirements, time rules, and recovery paths differ too.

The safest requirement therefore begins with an action ladder and a refusal path. The bot should choose the smallest action that matches the reviewed incident, show the exact target and duration, verify current rights, and record the result. If the current SDK cannot perform or verify a step, the bot should stop for manual review instead of reporting success.

Choose the smallest effective action

The aiogram 3.31.0 method references distinguish four operations:

Action	What it changes	Recovery question
Delete	Removes one identified message when Telegram's time and permission rules allow it	Was any other content or member state changed?
Restrict	Changes one supergroup member's allowed actions, optionally until a time	What complete permission set should be restored?
Ban	Removes a member and prevents return through an invite until unbanned	Were earlier messages also removed, and should rejoining be allowed?
Unban	Allows a banned person to join again; it does not add them back automatically	Is the target actually banned right now?

A warning or human review can be a valid first step even though it is not a Telegram moderation method. Do not make “ban” the default fallback when a delete or short restriction fails.

Check the requester, target, and bot separately

Three identities matter before a sensitive action:

• Requester: Is this a currently authorized, identifiable administrator for this community and this action?
• Target: Is the selected user still the intended member, and what is their current membership state?
• Bot: Does the bot currently have the specific right required by the requested action?

The python-telegram-bot ChatMemberAdministrator reference separates can_delete_messages from can_restrict_members; the latter covers restricting, banning, and unbanning. A generic “the bot is an administrator” check is not enough. The aiogram getChatMember reference also says results for other users are guaranteed only when the bot is an administrator, so failed verification must not be treated as proof that a target has left.

Use stable chat and user IDs, not display names. If the request came from an anonymous chat identity or an expired button, require a fresh, attributable confirmation before deleting content or changing membership.

Treat permissions as a complete state

restrictChatMember accepts a ChatPermissions object. Its use_independent_chat_permissions flag changes how one permission implies several others. A request that says only “disable media” is underspecified unless it also defines whether text, polls, previews, reactions, invitations, and each media type should remain available.

The python-telegram-bot ChatPermissions page adds a useful caution: it has observed unspecified permissions being set to false, while noting that this behavior is not formally documented and may change. Treat that as a reason to be explicit, not as a permanent Telegram guarantee.

Before applying a restriction, construct the full intended permission vector. Afterward, read the state again when the current interface supports it and compare every relevant field. To restore access, use a saved intended baseline or a reviewed policy—not “flip the last field back to true.”

Make durations unambiguous

The restrictChatMember and banChatMember references use until_date, but values more than 366 days or less than 30 seconds from the current time are treated as permanent. A duration parser that turns “30m” into the wrong unit can therefore create a permanent action.

Store both the requested duration and the computed absolute time. Reject ambiguous text, dates in the past, and values outside the approved policy. Show the administrator a human-readable time with timezone before confirmation, then verify the resulting membership state.

Message deletion has a different clock. The deleteMessage reference says a message generally must be less than 48 hours old, with additional rules for service messages, dice messages, chat types, and administrator rights. A failed delete should become a reviewable result such as “outside the deletion window,” not trigger an automatic ban.

Understand what cannot be undone

Ban and delete operations can remove information that code rollback cannot restore. The banChatMember reference says revoke_messages is always true for supergroups and channels. Ask separately whether the reviewed policy permits that effect; do not label ban as a reversible mute.

Unban is not a restore button. The unbanChatMember reference says the person does not automatically rejoin. It also warns that, without only_if_banned, calling unban for a current member can remove that member while leaving them eligible to return. Verify the current state and use an “only if banned” guard when available.

Keep a manual recovery path. It should state what an administrator must check in Telegram, what the bot can verify afterward, and which effects—such as deleted content—cannot be reconstructed.

Separate planning, confirmation, and execution

Model each moderation attempt as a small state machine:

1. Proposed: save chat ID, target user ID, source message ID when relevant, requested action, permission vector, duration, requester, and an expiration time.
2. Confirmed: show the target, action, side effects, and recovery path to the same authorized requester. Use a one-time confirmation token.
3. Applied or failed: call the supported method once, then record the returned result and any verified post-state.

Use an idempotency key so a repeated button, webhook delivery, or timeout retry cannot apply the action twice. Expired, already-used, cross-chat, cross-user, or changed-target confirmations should fail closed.

An audit record usually needs identifiers, policy reason, actor, timestamps, intended state, result, and error category. Do not retain the full deleted message by default merely to prove deletion; decide separately whether evidence storage is necessary and authorized.

A requirement you can give to AI

Build a private moderation flow for a Telegram supergroup. Authorized, identifiable administrators can select one reported message and choose: delete the message, restrict the member for an approved duration, ban the member, or unban only if currently banned. Never infer the action from free-form text alone. Before confirmation, show the chat, stable target user ID, action, full permission state, duration with timezone, message-removal effects, and recovery path. Recheck the requester's authorization, the bot's exact current rights, and the target's current state. Use one-time, expiring confirmation records and an idempotency key. A failed delete must not escalate automatically. Store a minimal audit result without copying deleted content by default. If the fixed SDK cannot perform or verify a required step, stop with a manual-review instruction and do not report success.

Start with one controlled test supergroup and a narrow moderator allowlist. Add automatic detection or bulk actions only after the manual flow and its failure cases are proven.

Acceptance checks after publishing

• A reviewer can see the difference between delete, restrict, ban, and unban before confirming.
• A user without current authorization cannot confirm a saved action.
• Missing can_delete_messages blocks deletion; missing can_restrict_members blocks restriction, ban, and unban.
• A restriction preserves every permission that the approved policy says should remain enabled.
• Durations below 30 seconds, above 366 days, in the past, or in an unexpected timezone are rejected or explicitly labeled permanent.
• A message older than the allowed deletion window produces a failure without changing membership.
• Retrying the same confirmation does not repeat the action.
• Unban with a non-banned target does not remove a current member.
• The audit trail distinguishes rejected, failed, applied, and manually reviewed outcomes.
• Rolling back bot code does not claim to restore deleted messages or reverse completed membership changes.

These are proposed tests for controlled chats. They are not evidence that any generated bot or current SDK has already passed them.

Where BotFatherV2 fits—and its boundary

BotFatherV2 helps turn a Telegram bot requirement into versioned code through an AI conversation. On 24 October 2026, the required /en-US homepage remained inaccessible, so the accessible English homepage is included as a fallback.

The public Build with AI documentation says that users review a requirement card before generating a version and that validation uses a fixed SDK surface without arbitrary npm modules or Node/Bun runtime APIs. The references in this article explain Telegram action semantics; they do not establish that every cited method exists in the current BotFatherV2 SDK.

AI-assisted development does not make the deployed bot an autonomous moderation agent. Keep human confirmation for consequential actions, review generated source and validation results, and test the exact current rights and state transitions in Telegram. BotFatherV2 is an independent product and is not affiliated with Telegram's official BotFather.

Sources and verification notes

• aiogram team, deleteMessage, v3.31.0 English reference; no individual publication date shown.
• aiogram team, restrictChatMember, v3.31.0 English reference; no individual publication date shown.
• aiogram team, banChatMember, v3.31.0 English reference; no individual publication date shown.
• aiogram team, unbanChatMember, v3.31.0 English reference; no individual publication date shown.
• aiogram team, getChatMember, v3.31.0 English reference; no individual publication date shown.
• python-telegram-bot project, ChatPermissions and ChatMemberAdministrator, v22.8 English references; no individual publication dates shown.

All pages were checked on 24 October 2026. This article turns method definitions into an original action ladder, confirmation protocol, recovery plan, and acceptance checklist. It does not present the access date as a Telegram feature release date.