Warnings, Reports, and the Moderation Log

Introduction

Not every moderation decision should be an instant ban. A member who breaks a rule once may just need a nudge; a member who keeps breaking rules should face a clear, predictable consequence. This group of features gives admins a graduated way to handle behaviour — a warning ladder that escalates to a ban only after repeated strikes, a way for ordinary members to flag bad messages for admins, and a private log that records what the moderation system did.

Each feature is off by default and takes no action until an admin enables it in the group dashboard. Turning the bot on does not silently start warning or banning anyone.

The warning ladder

The warning ladder lets admins issue strikes to a member. When the strike count reaches a configured limit, the member is banned automatically and their count resets. It is controlled by two settings:

• set_warnings_enabled — the on/off switch. Off by default.
• set_warn_limit — the number of strikes that triggers a ban. Default 3.

Three admin-only commands manage strikes:

• /warn — issue a strike. Reply to the member's message, or pass their numeric id or @handle. You can add an optional reason, for example /warn @user spamming links.
• /unwarn — remove one strike from a member, in case a warning was issued by mistake.
• /warns — check how many strikes a member currently has, out of the limit.

When a /warn pushes a member to the limit — for example, their third strike with the default limit of 3 — the bot bans them and clears their strike count. Below the limit, the bot records the new strike and replies with the current count, so both the admin and the member can see where things stand. The command message itself is removed after it is processed, keeping the visible chat tidy.

All three commands are admin-only. A regular member who runs them is refused, and no one can warn themselves.

Member reports

Reports let ordinary members flag a message for the admins' attention. This is deliberately a member feature, not an admin one: the people reading the chat are often the first to notice a problem. It is controlled by a single setting:

• set_reports_enabled — the on/off switch. Off by default.

To report a message, a member replies to it and sends /report, optionally with a short reason. The bot posts an in-group notice so admins can see which message was flagged and by whom, and records the report in the moderation log if one is set up.

Two rules keep reports from becoming a nuisance:

• Rate limiting. Each member can only report once every 30 seconds. Repeat reports inside that window are quietly ignored, so no one can spam the admins with report notices.
• Tidy chat. The /report command message is always deleted after it is handled, whether or not the report goes through, so the flagged conversation is not cluttered with report commands.

A report does not punish anyone on its own. It is a signal to admins, who then decide whether to warn, mute, ban, or take no action.

The moderation log

The moderation log mirrors what the moderation system does to a separate channel, so admins have a running record without watching the group in real time. It is controlled by one setting:

• set_modlog_channel_id — the numeric id of the channel that receives the log. Set it in the group admin dashboard under the Auto-Moderation section. Leaving it empty (the default) disables the log.

When a channel id is set, the bot posts a one-line entry for moderation events as they happen. These include warnings issued, bans (both warning-limit bans and other automated bans such as a banned known abuser), member reports, and raid lockdowns. Each entry names the action, the member it concerns, and the admin or system that took it.

For the log to work, the bot must be an admin of the target channel — that is what allows it to post there. If the bot is not an admin of the channel, the log entries cannot be delivered. The log is best-effort: a failure to post a single entry never blocks the moderation action itself, which still happens in the group.

How these features fit together

These three features are complementary. Reports let members surface problems. The warning ladder lets admins respond in proportion, escalating only when a member does not stop. The moderation log records both, giving the admin team a shared history of what happened and who acted. A common setup is to enable all three: members report, admins warn, and everything lands in the log channel for review.

Best practices

• Set the warning limit to match your community's tolerance. A limit of 3 gives members two chances before a ban; raise it for a lenient group, lower it for a strict one.
• Prefer issuing /warn as a reply to the offending message — it targets the right member with the least chance of a mistyped id.
• Use /warns before a ban decision to check whether a member is a repeat offender or a first-timer.
• Create a private moderation-log channel, add the bot as an admin there, and set its id in the dashboard so your team has an audit trail.
• Enable reports in larger groups where admins cannot read every message; the members become an extra set of eyes.

Summary

Warnings, reports, and the moderation log turn moderation from a series of one-off bans into a system. Members flag problems with /report, admins issue graduated strikes with /warn, /unwarn, and /warns, a member is banned automatically only after reaching the configured limit, and every action is mirrored to a log channel when one is configured. All of it stays off until an admin enables it, and the warning commands are restricted to admins.