User Intelligence and Group Analytics Dashboard

Introduction

The User Intelligence and Group Analytics system provides comprehensive data-driven insights into your Telegram community's health, member behavior, and moderation effectiveness. This sophisticated analytics platform goes far beyond simple message counts, offering deep behavioral analysis, risk assessment profiles, real-time monitoring capabilities, and detailed statistical breakdowns that help administrators make informed moderation decisions.

Unlike basic group statistics that only show surface-level metrics, the Intelligence and Analytics dashboard employs advanced data science techniques to reveal patterns, identify potential problems before they escalate, and provide actionable intelligence about individual users and overall community dynamics. The system combines historical data analysis, real-time event streams, and predictive risk modeling to create a comprehensive view of your community's operational status.

This feature set includes individual user intelligence reports (showing behavioral patterns, violation history, and spam risk scores), group-level statistics dashboards (displaying aggregate metrics, violation breakdowns, and engagement patterns), live punishment feeds (real-time streams of moderation actions across all your groups), and public API access for programmatic integration with external tools.

How It Works

User Intelligence Reports

The User Intelligence system maintains detailed behavioral profiles for every user in your community. When you search for a specific user by name, handle, or Telegram ID, the system retrieves their complete interaction history including messages sent, violations received, punishment duration, group membership patterns, and calculated risk scores.

The intelligence report begins with a comprehensive spam risk assessment calculated by the AI Spam Intelligence algorithm. This rating (0.0 to 1.0) reflects the statistical likelihood that the user is a spammer or malicious actor based on multiple behavioral signals including offense rate, violation confidence levels, profile characteristics, and engagement patterns.

Below the risk score, the system displays detailed violation statistics showing confidence metrics (mean, median, 95th percentile), high confidence violation rate, most common violation types, and most common violation reasons. These statistics help administrators understand not just that a user violated rules, but how confidently those violations were detected and what patterns characterize the user's problematic behavior.

The full violation history appears as a chronological list showing each offense with its timestamp, violation type (porn, sexual content, toxic language, spam, badwords, etc.), confidence level (0.0-1.0), and detailed reason explaining what triggered the detection. This transparency allows administrators to evaluate whether violations represent genuine problems or potential false positives.

Group Statistics Dashboard

The Group Statistics dashboard provides aggregate insights into your community's overall health and moderation effectiveness. The system calculates and displays multiple categories of metrics:

Overview Metrics include group status (allowed/not allowed), total member count, administrator count, bot presence verification, and whether the group has a profile picture and invite link properly configured.

Activity Metrics show total messages sent in the group's history, total violations detected, total punishment time administered (in minutes), and the relationship between these numbers indicating overall community compliance levels.

Moderation Efficiency metrics calculate punishment rate per 1,000 messages (showing how frequently moderation occurs relative to activity), average punishment duration (indicating typical violation severity), and average messages per member (engagement indicator).

Temporal Analysis displays activity over recent time periods (last 7 days, last 30 days) showing trends in violations and punishment patterns that help identify whether your community is becoming more or less problematic over time.

Violation Breakdown categorizes all violations by type (pornographic content, sexual content, toxic language, spam, language violations, profanity, insults, threats, badwords, forwarded messages, prohibited media, invite links, unauthorized bots) with exact counts for each category. This breakdown reveals which rules are most frequently violated, informing decisions about whether certain restrictions should be tightened or relaxed.

Live Punishment Feed

The real-time punishment feed uses WebSocket subscriptions to stream moderation events as they occur across all groups where your bot is active. This live view displays the most recent 20 punishments system-wide (not limited to your own groups), showing the user who was punished, violation type, detailed reason, confidence score, and timestamp.

The feed updates instantaneously when new violations occur anywhere in the monitored ecosystem, providing a real-time window into ongoing moderation activity. This transparency helps administrators:

• Monitor active spam campaigns affecting multiple communities
• Observe the bot's real-time decision-making process
• Identify users who violate rules across multiple groups
• See which violation types are currently most common
• Verify that the moderation system is actively working

Each punishment entry is clickable, allowing you to generate a full User Intelligence report for the violator with a single click. This lets you investigate quickly when you notice concerning patterns in the feed.

Public API Access

The User Intelligence system exposes a public REST API endpoint that allows anyone to query spam ratings for Telegram users by providing their user ID. The API returns the spam rating (0.0-1.0) and risk level category (Low, Medium, High, Critical) in JSON format without requiring authentication.

This public API enables third-party integrations, allowing other bot developers, researchers, or community moderators to incorporate the intelligence data into their own tools and workflows. The API documentation includes code examples in multiple languages (cURL, JavaScript, Python) showing how to make requests and parse responses.

While the spam rating is public, detailed violation histories and behavioral analyses remain private, visible only to administrators of groups where the queried user is a member. This privacy balance provides useful risk information to the broader Telegram ecosystem while protecting individual user privacy.

Configuration

Accessing User Intelligence

To view individual user intelligence reports:

1. Navigate to the "User Intelligence" section from your panel's main menu
2. Select the "User Intelligence" tab (first tab)
3. Use the search interface to find users by:
   • Full name or partial name match
   • Telegram handle (with or without @ symbol)
   • Telegram user ID (numeric)
4. Click on a user in the search results to view their full intelligence report
5. Review their spam rating, violation statistics, and complete violation history

The search function works across all users in groups where you are an administrator, allowing you to investigate any community member whose behavior concerns you.

Viewing Group Statistics

To access your group's analytics dashboard:

1. Navigate to your group's management page from the panel
2. Select the "Statistics" tab
3. Choose the "Group Statistics" sub-tab
4. Review the comprehensive metrics displayed across multiple sections:
   • Overview (status, membership, bot configuration)
   • Activity (messages, violations, punishments)
   • Moderation Efficiency (rates, averages, engagement)
   • Recent Activity (7-day and 30-day trends)
   • Top Violations (breakdown by type)
   • Timestamps (last activity, last update)

Statistics update in real-time as new data arrives, ensuring you always see current metrics.

Accessing User Statistics Within Groups

To view top active members in a specific group:

1. On your group's management page, select the "Statistics" tab
2. Choose the "Users Statistics" sub-tab
3. Use the search function to filter users by name, handle, ID, or bio content
4. Review the list showing the top 50 most active users by message count
5. Each user card displays:
   • Avatar (if available)
   • Name and handle
   • Total message count in this group
   • Last seen timestamp
6. Click any user to view their full intelligence report

This feature helps identify your most engaged community members and spot unusual activity patterns (e.g., users with very high message counts but no visible engagement might be spam bots).

Monitoring Live Punishment Feed

To watch real-time moderation events:

1. Navigate to "User Intelligence" from the main panel menu
2. Select the "Live Punishments" tab
3. Observe the stream of recent violations showing:
   • User avatar and name
   • Violation type and detailed reason
   • Confidence score
   • Timestamp (relative time ago)
   • Connection status indicator (showing WebSocket health)
4. Click any punishment entry to view the violator's full intelligence report

The feed automatically reconnects if the connection is lost, ensuring continuous monitoring.

Using the Public API

To programmatically access user spam ratings:

1. Navigate to "User Intelligence" → "API Documentation" tab
2. Review the API endpoint URL and format
3. Copy the provided code examples in your preferred language:
   • cURL (command line)
   • JavaScript (fetch API)
   • Python (requests library)
4. Replace the example user ID with the ID you want to query
5. Execute the request to receive JSON response containing:
   • spam_rating: Numeric score (0.0-1.0)
   • risk_level: Category string (Low/Medium/High/Critical)

The API is rate-limited to prevent abuse but allows reasonable query volumes for legitimate use cases.

Real-World Scenarios

Scenario 1: Investigating Suspicious New Members

A community administrator notices several new members joining simultaneously and wonders whether they're part of a coordinated spam operation. Using the User Intelligence search, the admin queries each new member's profile.

The intelligence reports reveal that all new members have:

• Spam ratings above 0.70 (high risk)
• No Telegram handles (red flag for spam accounts)
• Membership in 200+ groups with minimal messages per group (bot characteristic)
• NSFW profile pictures (common spam tactic)

Armed with this intelligence, the administrator preemptively bans the accounts before they can post spam, preventing disruption to the community. Without the intelligence data, the admin would have had to wait for the first spam messages to appear before taking action.

Scenario 2: Evaluating False Positive Reports

A long-time community member messages the administrators claiming they were unfairly muted for posting a legitimate message. The admins are unsure whether the bot made a mistake or the user is complaining about justified enforcement.

Using the User Intelligence report, administrators see:

• Spam rating: 0.15 (very low, trusted user)
• Single violation in 6-month history
• Violation confidence: 0.52 (borderline, low confidence)
• Violation type: Sentiment analysis - profanity detection
• Detailed reason: Message contained word that triggered false positive

The low confidence score and single violation support the user's claim of a false positive. The administrators explain the automated detection process, clarify that the restriction was only 1 minute, and reassure the user that their overall standing in the community remains excellent (0.15 spam rating).

Scenario 3: Monitoring Moderation Effectiveness

A community has recently tightened several moderation rules and wants to evaluate the impact. Using the Group Statistics dashboard, administrators review:

• Punishment rate: Increased from 2.5 to 4.8 per 1K messages
• Average punishment duration: Stable at 3.2 minutes
• Total violations (last 7 days): 45 (up from 28 previous week)
• Top violation: NSFW images (18 violations)

The statistics reveal that stricter image scanning is catching more inappropriate content (expected) but the punishment rate remains reasonable (still only 0.48% of messages violate rules). The administrators conclude the new settings are working as intended without over-moderating.

Scenario 4: Identifying Cross-Group Spam Patterns

An administrator monitoring the Live Punishment Feed notices the same usernames appearing repeatedly with similar violations (spam pattern detection, invite links) across different groups within minutes of each other.

This pattern indicates a coordinated spam campaign targeting multiple communities simultaneously. The administrator checks the User Intelligence report for one of the spammers, confirms a high spam rating (0.85+), and then searches for similar usernames to identify related accounts.

By proactively banning these related accounts from their own groups before the spam wave reaches them, the administrator prevents the attack rather than reacting to it after spam appears.

Scenario 5: Data-Driven Rule Optimization

A gaming community reviews their Group Statistics monthly to optimize moderation settings. This month's data shows:

• Top violation: Language enforcement (35 violations)
• Second: Toxic language (12 violations)
• NSFW violations: 2

The high language enforcement violation count surprises the admins—they discover their community has become more international with members speaking multiple languages, but the bot is still enforcing English-only rules.

Based on this data-driven insight, they disable language enforcement, recognizing their community has naturally evolved to be multilingual. The statistics helped them identify a rule that was no longer appropriate for their community's current composition.

Best Practices

Regular Intelligence Audits

Schedule weekly or monthly reviews of key intelligence metrics:

• Check Group Statistics dashboard for trends
• Review top violators in User Statistics
• Examine violation type distribution for patterns
• Monitor punishment rates and durations

Regular audits help you catch emerging problems early and verify that moderation settings remain appropriate as your community evolves.

Investigate Anomalies

When you notice unusual patterns in the data, investigate immediately:

• Sudden spike in violations might indicate spam attack or misconfigured settings
• Unusually high spam ratings for known good users might indicate false positives
• High message counts with low engagement might indicate bots
• Unusual violation confidence distributions might reveal systematic detection issues

Intelligence data helps you spot these anomalies; investigation helps you understand and address them.

Use Intelligence for Ban Appeals

When users request unbanning or appeal restrictions, use intelligence reports to make informed decisions:

• Review their complete violation history (not just latest incident)
• Examine confidence scores (low confidence violations might be false positives)
• Check spam rating (0.2 or below generally indicates legitimate user)
• Consider violation patterns (isolated incident vs. repeated problems)

Data-driven appeal evaluation ensures consistent, fair moderation decisions.

Share Insights with Co-Admins

Use the statistics dashboards as a communication tool among your moderation team:

• Screenshot weekly stats to share in admin chat
• Discuss trends and whether settings need adjustment
• Coordinate responses to emerging spam patterns
• Build institutional knowledge about your community's dynamics

Transparency with your team creates better collective moderation.

Use the Public API for Integrations

If you manage multiple communities or use additional moderation tools, integrate the public API:

• Query spam ratings before accepting new members
• Cross-reference with external spam databases
• Build custom dashboards combining data from multiple sources
• Automate risk-based moderation decisions

The API enables sophisticated workflows beyond the web interface.

Monitor Live Feed Periodically

Make checking the Live Punishment Feed part of your regular admin routine:

• Spot-check that enforcement is working correctly
• Identify coordinated spam campaigns early
• Track which violation types are currently most common
• Verify confidence scores match actual content quality

The real-time feed provides situational awareness that delayed statistics cannot.

Integration with Other Features

Foundation for AI Spam Intelligence

User Intelligence reports provide the transparency that makes AI Spam Intelligence trustworthy. When the AI automatically kicks a user with a spam rating above 0.75, administrators can review the intelligence report to understand exactly why that rating was calculated and verify the decision was appropriate.

The violation history, confidence statistics, and behavioral analysis shown in intelligence reports are the raw data that feeds the AI's risk calculation algorithm. This integration creates a closed loop: the AI makes decisions based on data, and administrators can audit those decisions by viewing the same data.

Complement to Manual Moderation

While automated systems handle routine enforcement, intelligence data helps administrators make nuanced decisions about edge cases:

• Borderline spam scores (0.60-0.74) might warrant warnings rather than kicks
• Low confidence violations might deserve second chances
• Users with good long-term history but recent violations might be coached rather than punished

The intelligence system provides the context that pure automation cannot.

Amplification of Pattern Detection

Individual intelligence reports show user-level patterns, while group statistics reveal community-level patterns:

• Many users violating the same rule suggests the rule might be too strict
• High violation rates at specific times indicate when spam campaigns occur
• Changing violation type distributions show how spam tactics shift over time

Combining both perspectives creates comprehensive pattern awareness.

Validation for Feature Configuration

Use statistics to validate whether your feature settings are working as intended:

• If NSFW detection generates many violations, it's catching content (working)
• If sentiment analysis shows zero violations despite toxic chat, threshold might be too high
• If spam detection misses obvious spam, threshold might be too strict

Data-driven validation ensures features are configured optimally for your community.

Advanced Usage

Correlation Analysis

Advanced administrators can correlate different metrics to derive insights:

• Punishment rate vs. activity level: High-activity groups with low punishment rates have healthy cultures
• Violation confidence vs. violation type: Low confidence NSFW violations might indicate overly sensitive threshold
• User spam rating vs. group membership count: Users in many groups with high spam ratings are likely professional spammers
• Temporal patterns: Violations clustering at certain times might indicate targeted spam campaigns

Look for these correlations to understand deeper patterns in your community dynamics.

Cohort Analysis Using User Statistics

Track specific user cohorts to understand community health:

• New members (joined last 30 days): What percentage accumulate violations?
• Top contributors (high message counts): Do they have low spam ratings?
• Dormant members (no recent activity): Are they re-engaging or leaving?

Cohort analysis reveals whether your community is retaining quality members and successfully integrating newcomers.

Violation Confidence Distribution Analysis

The intelligence report shows confidence mean, median, and 95th percentile. Use these to understand detection quality:

• High mean + high median (both >0.7): Strong, confident detections
• Low mean + high 95th percentile: Mostly weak detections with occasional strong ones
• High standard deviation (large gap between mean and percentile): Inconsistent detection quality

These patterns help you evaluate whether moderation settings are producing reliable results.

Benchmark Against Historical Data

Track key metrics over time to establish baselines and identify trends:

• What's your normal punishment rate per 1K messages?
• What's typical violation distribution (which types most common)?
• How does spam rating distribution look for your community?

With historical baselines established, anomalies become immediately obvious.

Risk Stratification

Categorize users into risk tiers based on spam ratings:

• 0.00-0.30: Trusted users (green)
• 0.31-0.60: Normal users (yellow)
• 0.61-0.74: Elevated risk (orange)
• 0.75+: High risk (red, auto-kicked if AI enabled)

Apply different monitoring or enforcement policies to each tier. For example, elevated risk users might receive faster escalation to restrictions, while trusted users might get more lenient treatment for borderline violations.

Technical Implementation

The User Intelligence system operates as part of the telegram_intelligence microservice, which maintains a continuously-updated database of behavioral profiles derived from violation events, message statistics, group membership data, and profile information.

The spam rating calculation employs a statistical model combining Bayesian probability theory with logistic risk curves. The algorithm weights multiple factors including offense rate (violations / messages), confidence distributions (mean, median, percentile), violation type prevalence, behavioral signals (profile characteristics, group membership patterns), and reputation factors (admin status, engagement levels).

Group statistics are calculated through database aggregation queries that sum violations, message counts, punishment durations, and other metrics across all recorded events for the group. The queries employ efficient indexing and caching to ensure dashboard load times remain fast even for groups with extensive history.

The live punishment feed uses GraphQL subscriptions over WebSocket connections, streaming real-time events from the tg_punishments table as new rows are inserted. The subscription query includes a limit (20 most recent punishments) and orders by creation timestamp descending to show latest events first.

The public API endpoint provides a simple REST interface that accepts user ID parameters and queries the intelligence database for the corresponding spam rating. Response formatting follows standard JSON conventions with appropriate CORS headers to allow cross-origin requests from web applications.

All intelligence data is stored in the PostgreSQL database with appropriate indexes on frequently-queried fields (user_id, group_id, created_at, violation_type) ensuring fast retrieval even as the dataset grows to millions of records.

Privacy & Data Handling

The User Intelligence system processes and stores:

• Violation records: Type, timestamp, confidence, details
• Message statistics: Counts per user per group
• Group membership: Which groups users belong to
• Profile information: NSFW status, handle presence, bio content (if scanned)
• Calculated metrics: Spam ratings, confidence statistics

All data is derived from information available through Telegram's API or generated through the bot's moderation actions. The system does not access message content directly—it receives violation reports from content analysis systems that already scanned messages under configured moderation settings.

Privacy protections include:

• Access control: Only group administrators can view detailed intelligence for users in their groups
• API limitations: Public API provides only spam rating, not detailed violation history
• Data minimization: Violation logs store violation type and confidence, not full message content
• Anonymization: Aggregate statistics do not reveal individual user identities

Users cannot opt out of having their behavior analyzed (as this would allow spammers to evade detection), but their detailed histories remain private to their group administrators. The public API's limited data exposure balances community protection (sharing risk information) with individual privacy (protecting violation details).

Troubleshooting

"Cannot find specific user in intelligence search"

Possible causes:

• User has not interacted with any groups where your bot is present
• Searching by incorrect name/handle format
• User recently joined and hasn't been fully indexed yet

Solution: Users only appear in search if they've been active in groups monitored by the bot. Ensure you're searching by exact Telegram handle (try with and without @ symbol) or numeric user ID. New users may take a few minutes to fully index after first activity.

"Group statistics show zero violations despite known rule breaches"

Possible causes:

• Violations occurred before bot was added to group
• Feature that would catch violations not enabled
• Violations happening but not being logged properly

Solution: Check that relevant moderation features are actually enabled in settings. Review individual user intelligence reports for known violators to verify their violations are being recorded. Statistics only include violations detected by the bot, not pre-existing problems.

"Live punishment feed shows 'disconnected' status"

Possible causes:

• WebSocket connection lost due to network issue
• Browser tab was inactive for extended period
• Server maintenance or restart

Solution: The feed should automatically reconnect within 30 seconds. If it remains disconnected, refresh the page. Check connection status indicator—if it shows "connected" but no punishments appear, this might indicate a period of zero violations (normal during quiet periods).

"Spam ratings seem lower than expected for obvious spammers"

Possible causes:

• Spammer hasn't accumulated enough violations yet
• Violations have low confidence scores
• Spammer has positive reputation signals offsetting violations

Solution: Spam ratings reflect statistical likelihood based on accumulated data. New spammers with few violations won't have high ratings until they establish a pattern. Review their intelligence report to see confidence scores—if violations have low confidence (0.50-0.60), the algorithm appropriately assigns lower risk. The rating will increase as more high-confidence violations accumulate.

"Public API returns error or empty response"

Possible causes:

• Invalid user ID format
• User has never interacted with bot-monitored groups
• Rate limiting triggered

Solution: Ensure you're providing a valid numeric Telegram user ID, not a username or handle. The API only returns data for users who have been active in groups where the bot operates. If making many requests, slow down to avoid rate limits (max 100 requests per minute per IP).

"User Statistics shows fewer than 50 users despite larger group"

Possible causes:

• Many members have zero messages
• Search filter is active and limiting results
• Inactive members not included in top contributors list

Solution: The Users Statistics list shows only users who have sent at least one message, ordered by message count. Members who joined but never participated won't appear. Clear any active search filters to see full list. The count only includes active participants, not total membership.

Conclusion

The User Intelligence and Group Analytics system gives you visibility into your community's dynamics, member behavior, and moderation effectiveness. It combines individual behavioral profiles with aggregate statistics, real-time monitoring, and public API access.

Whether you need to investigate a suspicious user, evaluate whether your moderation settings are working correctly, monitor ongoing spam campaigns in real-time, or integrate intelligence data into external tools, the analytics dashboard provides the insights you need to make informed decisions quickly and confidently.

The transparency of the intelligence reports ensures that automated moderation decisions remain auditable and explainable—administrators can always review exactly why a user received a particular spam rating or what violations contributed to an enforcement action. This accountability makes automated moderation trustworthy and helps administrators maintain community trust even when enforcement actions occur.

Used regularly, these reports let you moderate proactively rather than reactively—reviewing spam ratings and the punishment feed surfaces problems before they spread, and the audit trail keeps every automated decision reviewable.