Automated Punishment System and Violation Enforcement

Introduction

The Automated Punishment System represents the enforcement engine that transforms violation detection into concrete moderation actions, providing consistent, proportional, and escalating consequences for rule violations without requiring constant manual intervention from administrators. This sophisticated system analyzes each violation's severity, tracks cumulative punishment history, calculates appropriate restriction durations, and automatically enforces temporary mutes that prevent repeat offenders from continuing disruptive behavior.

Unlike simple binary moderation approaches that either ban users permanently or do nothing, the automated punishment system implements graduated enforcement that distinguishes between severity levels, recognizes repeat offenders, and applies restrictions proportional to the offense. A user posting borderline content once receives minimal consequence, while users repeatedly violating serious rules face increasingly strict restrictions that provide clear behavioral correction signals without immediately resorting to permanent bans.

The system operates entirely automatically once rules are configured, executing enforcement actions within milliseconds of detecting violations. Every punishment is logged with complete transparency, allowing administrators to audit decisions, review violation patterns, and verify that enforcement aligns with community standards. The combination of automation (handling routine violations consistently) and transparency (enabling human oversight of edge cases) creates moderation that's both efficient and accountable.

How It Works

Violation Detection and Classification

When any content analysis system (NSFW detection, sentiment analysis, spam detection, language enforcement, badwords filter, prohibited content rules) identifies a violation, it generates a violation report containing the violation type, confidence score, detailed reason, and timestamp. This report is immediately sent to the decision engine (telegram_decision microservice) that determines appropriate enforcement action.

The decision engine first classifies the violation into severity categories based on type:

High Severity (30-minute base restriction):

• Pornographic content (NSFW detection confidence ≥ threshold)

Medium-High Severity (15-minute base restriction):

• Sexual/racy content (NSFW detection below porn threshold but above racy threshold)

Medium Severity (5-minute base restriction):

• Toxic language (sentiment analysis - toxicity)
• Threats (sentiment analysis - threat detection)
• Spam content (spam pattern detection)
• Invite link posting (prohibited content - invite links)
• Unauthorized bot additions (prohibited content - other bots)

Low Severity (1-minute base restriction):

• Profanity (sentiment analysis - profanity detection)
• Insults (sentiment analysis - insult detection)
• Language violations (language enforcement)
• Badwords filter matches (custom badwords list)
• Forwarded messages (prohibited content - forwards)
• Prohibited media types (videos, GIFs, audio, files, text)

This classification ensures that punishment duration reflects violation severity—posting pornography receives 30x longer restriction than using profanity, accurately representing the relative seriousness of the infractions.

Cumulative Punishment Calculation

The system doesn't simply apply base durations in isolation. Instead, it tracks each user's cumulative punishment history and escalates restrictions for repeat offenders. When a new violation occurs, the decision engine:

1. Retrieves the user's total punishment time across all previous violations
2. Calculates the new punishment duration as: new_duration = base_duration + (cumulative_past_duration * escalation_factor)
3. Adds the new violation to the user's permanent history
4. Applies the calculated restriction

For example, a user's first profanity violation might receive a 1-minute restriction (base duration). If they violate again while already having 1 minute of cumulative punishment, the second violation receives approximately 1.5 minutes. A third violation with 2.5 cumulative minutes receives approximately 2 minutes. Punishment duration escalates with each violation, providing increasingly strong behavioral correction signals.

This cumulative approach recognizes that isolated mistakes deserve lenient treatment while persistent rule-breaking requires stronger intervention. Users who violate rules extensively eventually face restrictions of 15-30 minutes even for low-severity violations, making continued violation increasingly costly in terms of participation ability.

Automated Restriction Application

Once punishment duration is calculated, the system immediately applies a Telegram restriction to the user in the affected group. The restriction prevents the user from:

• Sending messages
• Sending media files
• Sending stickers and GIFs
• Sending polls
• Adding web page previews
• Changing chat information

The user remains in the group and can see messages, but cannot participate until the restriction expires. This "timeout" approach provides behavioral correction without the permanence of a ban—users get a clear signal that their behavior was unacceptable while retaining the opportunity to return and participate appropriately.

The restriction is time-limited and expires automatically without requiring administrator action. When the punishment duration elapses, Telegram automatically unrestricts the user, allowing them to resume normal participation. This automation eliminates the need for administrators to manually track and lift restrictions.

Message Deletion

Simultaneously with applying restrictions, the system deletes the offending message from the chat. This immediate removal serves multiple purposes:

• Prevents other members from seeing inappropriate content
• Stops spread of spam or malicious links
• Maintains community atmosphere by removing disruptive content
• Provides clear feedback to the violator about what was unacceptable

The deletion happens within milliseconds of violation detection, minimizing exposure to problematic content. In high-traffic groups, other members often never see violating messages because removal occurs faster than most users' message refresh cycles.

Administrator Exemption

The punishment system includes critical administrator protection that ensures group administrators are never restricted regardless of content they post. Before applying any restriction, the decision engine verifies whether the user has administrator status in the group.

If the user is an administrator, the system:

• Records the violation in statistics (for transparency)
• Deletes the message (if deletion is configured)
• Does NOT apply any restriction or punishment
• Logs the administrator exemption in violation records

This protection is absolute—administrators cannot accidentally mute themselves or their co-admins through the automated system. The exemption recognizes that administrators must retain the ability to manage their groups even if they occasionally post content that would violate rules for regular members (e.g., posting example spam to demonstrate what to avoid, sharing screenshots of violations being discussed, etc.).

Violation Logging and Transparency

Every violation and punishment is permanently logged in detailed records visible through the User Intelligence and Group Statistics dashboards. The logs include:

• Exact timestamp of violation
• Violation type and category
• Confidence score (for detection-based violations)
• Detailed reason explaining what triggered the detection
• Applied punishment duration
• Cumulative punishment time after this violation
• Whether the user was actually restricted (or exempted as admin)

This comprehensive logging ensures complete transparency and accountability. Administrators can review exactly why each restriction occurred, verify that punishments match violation severity, and identify patterns in member behavior that might inform moderation strategy adjustments.

Configuration

Enabling Automated Punishment

The punishment system operates automatically for any violations detected by enabled features. There are no separate "enable punishment" toggles—punishment is inherent to rule enforcement. However, the severity and behavior of punishments are influenced by your configured detection settings:

1. Navigate to your group's management page
2. Go to Settings > AI Moderation and Basic Protection tabs
3. Enable the detection features you want enforced:
   • NSFW content detection → Punishes pornographic/sexual content
   • Sentiment analysis → Punishes toxic language, profanity, insults, threats
   • Spam pattern detection → Punishes spam messages
   • Language enforcement → Punishes wrong-language messages
   • Badwords filter → Punishes custom prohibited words
   • Prohibited content rules → Punishes media types, forwards, invite links

Each enabled feature feeds violations into the punishment system, which applies appropriate restrictions automatically.

Adjusting Punishment Severity Through Thresholds

While base punishment durations are fixed by violation type, you can indirectly influence punishment frequency and severity by adjusting detection thresholds:

Stricter enforcement (more punishments):

• Lower NSFW detection threshold (0.60-0.70) catches more content
• Lower sentiment analysis threshold (0.60-0.70) catches more toxicity
• Lower spam detection threshold (0.60-0.70) catches more spam

Lenient enforcement (fewer punishments):

• Higher NSFW threshold (0.80-0.90) only catches obvious violations
• Higher sentiment threshold (0.80-0.90) only catches clear toxicity
• Higher spam threshold (0.80-0.90) only catches blatant spam

Threshold adjustment doesn't change punishment durations, but it determines how often punishments trigger. Stricter thresholds mean more frequent restrictions (including for borderline content), while lenient thresholds reserve punishments for unambiguous violations.

Delete-Only Modes

Some features offer "delete only" modes that remove violating content without applying punishment restrictions:

Language Enforcement:

• "Delete only mode" toggle removes wrong-language messages without punishing users
• Useful when members genuinely forget language requirements or make innocent mistakes

Badwords Filter:

• "Delete only (no punishment)" option removes messages containing badwords without restrictions
• Appropriate when filter might have false positives or community prefers gentle enforcement

These modes maintain content removal (preserving community atmosphere) while avoiding potentially harsh restrictions for low-severity violations.

Monitoring Punishment Activity

To review how the punishment system is operating:

1. Go to your group's Statistics tab
2. Select "Group Statistics" sub-tab
3. Review metrics including:
   • Total punishments administered
   • Total punishment time (in minutes)
   • Average punishment duration
   • Punishment rate per 1,000 messages
   • Violation type breakdown

These statistics reveal whether punishment frequency matches your expectations and whether certain violation types dominate enforcement activity.

Real-World Scenarios

Scenario 1: Escalating Enforcement for Repeat Offender

A user joins a community and immediately posts a mildly toxic comment. Sentiment analysis detects toxicity at 0.73 confidence (above 0.70 threshold), triggering a 5-minute restriction. The message is deleted and the user is muted for 5 minutes.

After the restriction expires, the user posts another toxic comment. Their cumulative punishment time is now 5 minutes. The new violation receives approximately 7 minutes restriction (5 base + escalation based on 5 cumulative). Total cumulative time becomes 12 minutes.

The user continues with a third toxic comment. With 12 minutes cumulative, the third violation receives approximately 10 minutes restriction. Total cumulative becomes 22 minutes.

By the fourth violation, the user faces 15+ minute restrictions for what started as 5-minute offenses. The escalating consequences make continued violation increasingly costly, providing strong behavioral correction incentive. Eventually, the user either adapts their behavior or their spam rating increases to the point where AI Spam Intelligence removes them automatically.

Scenario 2: Proportional Response to Severity

Two users violate rules: User A posts borderline profanity (low severity), User B posts pornographic content (high severity). Neither has previous violations.

User A receives a 1-minute restriction for profanity—a brief timeout that provides correction without being overly punitive for a first offense involving mild language.

User B receives a 30-minute restriction for pornography—a substantial timeout reflecting the serious nature of posting sexually explicit content.

The dramatically different punishments (1 minute vs. 30 minutes) reflect the dramatically different severity levels. The system correctly recognizes that all violations aren't equal and calibrates enforcement proportionally.

Scenario 3: Administrator Protection

A group administrator is explaining community rules to members and posts an example message containing profanity to demonstrate what's not allowed: "Don't post messages like 'this is f***ing stupid' - keep discussions respectful."

The sentiment analysis system detects the profanity in the example message and generates a violation report. However, the decision engine verifies the sender has administrator status and exempts them from restriction.

The violation appears in statistics (showing the detection system is working), but no restriction is applied. The administrator can continue explaining rules without accidentally muting themselves, while the logging ensures transparency that the exemption occurred.

Scenario 4: Cumulative History Across Violation Types

A user has the following violation history:

• Day 1: Profanity (1 min) - cumulative: 1 min
• Day 3: NSFW image (30 min) - cumulative: 31 min
• Day 5: Spam message (5 min + escalation) - cumulative: 37 min
• Day 7: Language violation (1 min + escalation) - cumulative: 40 min

By Day 7, even a low-severity language violation receives escalated punishment because the user's cumulative history across all violation types is 40 minutes. The system recognizes that a user who violates multiple different rules repeatedly is a persistent problem regardless of specific violation types.

This cross-type cumulation ensures that users can't circumvent escalation by diversifying their violations (posting toxic content, then spam, then NSFW, etc. to reset escalation). The punishment system tracks total violation pattern, not individual category patterns.

Scenario 5: Delete-Only Mode for Cultural Adjustment

An international community wants to maintain English as a primary language but has many non-native speakers who occasionally post in their native languages accidentally. The administrators want to enforce the language rule without punishing members for honest mistakes.

They enable language enforcement with "delete only mode." When users post non-English messages, the content is immediately removed (maintaining the English-language environment), but no punishment restriction is applied (recognizing these are likely mistakes rather than malicious violations).

Members receive feedback that their messages were removed (teaching the language rule), but they can immediately try again in English without waiting through a restriction timeout. This gentle enforcement maintains standards while accommodating learning curves.

Best Practices

Trust the Escalation System

Resist the temptation to manually intervene in punishment escalation for users with extensive violation histories. The system's cumulative escalation is designed to provide increasingly strong correction signals—users who continue violating after multiple escalated punishments demonstrate they won't modify behavior through gentle measures.

If a user accumulates 100+ minutes of cumulative punishment and continues violating, that pattern indicates they're not interested in following community rules. At that point, consider permanent ban rather than continuing with automated restrictions.

Review Administrator Exemptions

Periodically check violation statistics to see if administrators are generating violations. While administrators are exempted from punishment, frequent violations by admins might indicate:

• Admin is testing detection systems (expected and fine)
• Admin is posting example violations for educational purposes (expected and fine)
• Admin genuinely violates rules frequently (problematic—admins should model good behavior)

Use exemption data to ensure administrators maintain behavioral standards even though they're protected from punishment.

Calibrate Through Statistics

Use your Group Statistics dashboard to verify punishment frequency matches your intentions:

• If punishment rate is very high (10+ per 1K messages), consider whether thresholds are too strict
• If punishment rate is very low (<1 per 1K messages), consider whether thresholds are too lenient
• If specific violation types dominate (90%+ of one type), that might indicate threshold miscalibration

Data-driven calibration ensures your enforcement aligns with actual community needs.

Communicate Punishment to Members

Include information about the automated punishment system in your welcome message and group description:

"This group uses automated moderation. Violations of community rules result in temporary restrictions. Repeated violations result in increasingly longer restrictions. Administrators can review all punishments in case of disputes."

Transparency about automated enforcement helps members understand that restrictions aren't personal attacks from administrators—they're automatic consequences of rule violations.

Use Delete-Only Modes Strategically

Delete-only modes make sense for:

• Rules that are cultural preferences rather than critical boundaries (language requirements)
• Communities with many new or learning members (gentle enforcement)
• Violations that might have high false positive rates (badwords with slang overlap)

Don't use delete-only for serious violations (NSFW content, threats, spam)—those require punishment restrictions to create meaningful behavioral correction.

Monitor for System Abuse

Watch for users attempting to game the punishment system:

• Posting violations immediately before restrictions expire to avoid escalation wait time
• Using multiple accounts to avoid cumulative punishment history
• Posting borderline content that barely escapes detection thresholds

Address systematic attempts to circumvent enforcement with permanent bans rather than continuing automated restriction cycles.

Integration with Other Features

Foundation for AI Spam Intelligence

Every punishment contributes to the user's violation history that feeds into AI Spam Intelligence risk scoring. Users with extensive punishment records receive elevated spam ratings, and once that rating exceeds 0.75, AI Spam Intelligence automatically removes them from the group.

This creates a progression: automated punishments handle routine violations → persistent violators accumulate punishment history → AI recognizes the pattern → automatic removal prevents continued disruption.

Enforcement Mechanism for All Detection Systems

The punishment system serves as the shared enforcement mechanism for all detection features. Rather than each feature implementing its own punishment logic, they all feed into the centralized decision engine that ensures consistent enforcement across violation types.

This centralization prevents conflicts (multiple simultaneous restrictions), ensures escalation works across violation categories, and maintains consistent logging and transparency.

Deterrent for Prohibited Content

The immediate deletion + restriction combination makes violating prohibited content rules costly enough to deter casual violations. Users quickly learn that posting restricted media types results in immediate removal and timeout, creating behavioral conditioning against future violations.

The deterrent effect is particularly strong for low-severity violations (1-minute restrictions) that aren't harsh enough to cause resentment but annoying enough to discourage repetition.

Data Source for Group Statistics

Punishment records create the raw data that powers Group Statistics analytics. Administrators can see:

• Which violation types occur most frequently
• How punishment rates trend over time
• Whether specific members account for disproportionate violations
• How effective enforcement is at reducing repeat violations

This intelligence informs moderation strategy and helps identify areas where community culture might need attention beyond automated enforcement.

Advanced Usage

Understanding Escalation Mathematics

The escalation formula approximately follows: new_duration ≈ base_duration * (1 + (cumulative_minutes / 10))

This means:

• 0 cumulative → 1x base duration
• 10 cumulative → ~2x base duration
• 20 cumulative → ~3x base duration
• 50 cumulative → ~6x base duration
• 100 cumulative → ~11x base duration

Users with extreme violation histories (100+ minutes) face massive escalation that makes even minor violations result in 20-30 minute restrictions. This progression ensures that persistent violators eventually face consequences severe enough to either reform behavior or trigger AI spam removal.

Identifying Punishment Pattern Anomalies

Watch for unusual patterns in punishment data:

• All violations from single user: Might indicate targeted harassment or user genuinely not understanding rules
• Violations clustered at specific times: Might indicate spam attack waves or timezone-specific problems
• Sudden spike in specific violation type: Might indicate detection threshold misconfiguration or new spam tactic

Use these patterns to adjust settings or investigate deeper causes rather than simply accepting the raw punishment numbers.

Temporary Threshold Adjustment During Events

Consider temporarily tightening thresholds (lowering values) during vulnerable periods:

• After adding bot to new large group (higher spam risk initially)
• During known spam campaign waves
• During controversial events that might elevate tensions

Then relax thresholds back to normal once the high-risk period passes. This dynamic adjustment provides extra protection when needed without permanent over-enforcement.

Manual Review of Long Restrictions

When a user receives a very long restriction (20+ minutes), consider manually reviewing their violation history to verify the escalation is appropriate:

• Check if cumulative punishment comes from many minor violations or few serious ones
• Verify violations are genuine and not false positives
• Consider whether the user deserves a fresh start (if they had violations months ago but recent behavior was clean)

While automation handles most cases correctly, extremely long restrictions might warrant human verification.

Technical Implementation

The punishment system operates through the telegram_decision microservice that receives violation reports from all detection services and determines appropriate enforcement actions.

When a violation arrives, the decision service:

1. Queries the database for the user's punishment history
2. Sums total cumulative punishment time across all previous violations
3. Calculates new punishment duration using severity-based base duration + escalation formula
4. Verifies user is not a group administrator
5. Calls Telegram API to restrict the user with calculated duration
6. Calls Telegram API to delete the offending message
7. Records the violation in the database with full details

The restriction is implemented through Telegram's restrictChatMember API method with a timeout parameter. Telegram automatically unrestricts the user when the timeout expires, requiring no follow-up action from the bot.

All violation records are stored with JSONB details fields that preserve the complete context of each violation, including confidence scores, detection reasons, timestamp, punishment duration, and whether restriction was actually applied. This comprehensive logging enables detailed historical analysis and auditing.

The decision engine implements rate limiting to prevent punishment spam—if a user generates multiple violations within seconds (e.g., posting spam flood), the system batches violations to avoid applying dozens of simultaneous restrictions.

Privacy & Data Handling

The punishment system processes and logs:

• User identifiers: Telegram user ID and group ID
• Violation details: Type, confidence, reason, timestamp
• Punishment actions: Duration, whether applied, cumulative totals
• Message metadata: Not full content, only violation indicators

Violation logs do not store complete message text—only the specific detected violations (e.g., "sentiment analysis detected toxicity at 0.85 confidence" rather than storing the full toxic message). This minimizes privacy impact while maintaining enforcement transparency.

Punishment records are visible to group administrators through Statistics and User Intelligence dashboards. Records are not publicly accessible or shared outside the administrative interface.

Users are not directly notified of their cumulative punishment totals (to prevent gaming the system), but they can infer escalation from experiencing longer restrictions for repeat violations.

All punishment data is retained permanently for analytical and auditing purposes. Historical violation patterns contribute to spam risk assessments and help administrators understand long-term member behavior trends.

Troubleshooting

"Users getting restricted but don't seem to have violated rules"

Possible causes:

• Detection threshold set too low (catching borderline content)
• False positive from detection system
• Violation that was valid but you interpreted differently

Solution: Review the specific violation in User Intelligence report to see confidence score and detailed reason. If confidence is borderline (0.50-0.70), consider raising detection threshold. If it's a clear false positive, this is rare but possible—verify detection settings are appropriate for your community type.

"Users complaining restrictions are too harsh"

Possible causes:

• Escalation is working as designed for repeat offenders
• Base durations might not match community expectations
• Users don't understand the graduated enforcement system

Solution: Explain to users that restrictions escalate with repeat violations—what starts as 1 minute becomes 5+ minutes for persistent violators. Review the user's violation history to verify escalation is appropriate. Consider whether your community would prefer delete-only enforcement for certain violation types.

"Administrator accidentally muted themselves"

Possible causes:

• User doesn't actually have administrator status in Telegram group (only in bot panel)
• Bug in administrator detection (extremely rare)

Solution: Verify the user has actual administrator rights in the Telegram group settings (not just in the bot's dashboard). The exemption only applies to Telegram-level administrators. If they're truly an admin and got restricted, this is a bug—report it for investigation.

"Punishments not escalating for repeat violators"

Possible causes:

• Violations are spread across multiple groups (each group tracks separately)
• Viewing wrong user (similar username)
• Database issue preventing cumulative calculation

Solution: Punishment escalation is per-user per-group—violations in Group A don't escalate punishments in Group B. Verify you're looking at the correct user and correct group. If a user genuinely has multiple violations in one group with no escalation, this indicates a system malfunction that should be reported.

"Very long restrictions (30+ minutes) seem excessive"

Possible causes:

• User has extensive violation history (working as designed)
• Multiple violations occurred in rapid succession (cumulative calculation)
• Serious violation type (pornography has 30-minute base duration)

Solution: Review the user's complete violation history to understand their cumulative punishment time. Users with 100+ minutes of history face extreme escalation by design. If this seems inappropriate, consider whether the user deserves a fresh start or whether their pattern indicates they should be permanently banned instead.

Conclusion

The Automated Punishment System transforms violation detection into effective behavioral enforcement through intelligent escalation, severity-proportional consequences, and comprehensive transparency. By automatically applying restrictions that increase with repeat violations, the system provides clear feedback that guides members toward rule-compliant behavior without requiring constant manual intervention from administrators.

The balance between automation (handling routine enforcement consistently) and transparency (enabling administrative review of all decisions) creates moderation that's both efficient and accountable. Users receive immediate consequences for violations, administrators maintain full visibility into enforcement actions, and repeat offenders face escalating restrictions that create strong incentives for behavioral correction.

Combined with AI Spam Intelligence (which removes persistent violators automatically) and comprehensive violation logging (which enables data-driven moderation strategy), the punishment system creates a complete enforcement ecosystem that protects communities while minimizing administrative burden. Enable detection features today to activate automated punishment enforcement and experience consistent, proportional, and transparent moderation that scales with your community's size and complexity.