🔍

How Features Work

Technical details on how BeefyGuard features operate.

Portal Verification System

Verification Flow

  1. Admin runs /portal command in their group
  2. Bot DMs admin with "Create Portal" button
  3. Admin selects which private group(s) to protect
  4. Admin selects a public channel (bot must be admin)
  5. Admin chooses CAPTCHA type and customizes message
  6. Bot posts verification message to channel with "Tap to Verify" button
  7. User clicks button → opens deep link to bot
  8. Bot sends WebApp button → user opens verification page
  9. User completes CAPTCHA (button/math/emoji)
  10. On success, bot generates one-time invite link
  11. User receives link to join private group

CAPTCHA Types

  • Button: Simple "I'm not a robot" click
  • Math: Solve simple arithmetic (e.g., 5 + 3 = ?)
  • Emoji: Select matching emoji from choices

Security

  • Each invite link works once only
  • Links expire after use or timeout
  • Tokens are cryptographically random

Detection Algorithm

Similarity Matching

The bot uses fuzzy string matching to compare user names to admin names. The similarity threshold determines how similar names must be to trigger detection.

Profile Picture Matching

Uses perceptual hashing (pHash) to compare profile pictures. Generates a hash of each admin's profile picture and compares incoming users' pictures. Hamming distance below threshold triggers detection.

Detection Process

  1. User joins or changes name/picture
  2. Bot compares name to admin list
  3. Bot compares profile picture to admin pictures
  4. Calculates similarity scores
  5. If any score exceeds threshold, takes action

Background Scanning

Scan Process

  1. Bot periodically scans all group members
  2. Compares each member's name to admin list
  3. Takes action on matches
  4. Logs results to log channel (if set)

Scan Intervals

Configurable from 0 (disabled) to 1440 minutes (24 hours). Default is 30 minutes.

Spam Detection System

Cross-Chat Quote Detection

  1. Bot monitors all messages for external_reply attribute
  2. Extracts channel ID from the quoted message
  3. Checks if channel is on internal spam list
  4. Tracks channel usage count across all groups
  5. Takes action based on settings

Linked Channel Spam Detection

  1. Bot detects replies to linked channel posts
  2. Extracts ALL URLs from message (text + entities)
  3. Checks URLs against domain whitelist
  4. If spam link found, takes action

URL Extraction

The bot extracts URLs from:

  • Plain text (regex matching)
  • text_link entities (hidden hyperlinks)
  • url entities (marked URLs)

Reply-to-User Detection

  1. Bot monitors replies from low-activity users
  2. Checks if target user is admin (allowed) or not (suspicious)
  3. Tracks attempts per user
  4. Auto-bans after configurable threshold

First Message Link Detection

  1. Bot checks if this is user's first message
  2. Checks user's join date against grace period
  3. If first message AND within grace period AND contains link → ban
  4. Established users (messages > 0 OR joined > X hours) are exempt

Action System

Action Types

  • Delete: Remove message only
  • Warn: Send warning message
  • Restrict: Temporarily mute user (configurable duration)
  • Kick: Remove user (can rejoin)
  • Ban: Permanently ban user
  • Alert: Notify admins only (no action)

Action Priority

Actions are configurable per feature. Each spam type can have its own action.

Forum Topic Logging

How It Works

  1. Admin enables Forum Mode in their log channel (Telegram setting)
  2. Admin clicks "Auto-Create Topic" in dashboard
  3. Bot creates a topic named after the group
  4. All logs for that group go to that topic
  5. Multiple groups can use one log channel with separate topics

Log Channel Requirements

  • Must be a group (not channel)
  • Must have Forum Mode enabled
  • Bot needs "Manage Topics" permission

One-Tap Mod Actions

Button Types

  • Whitelist: Add user to whitelist (skip future detection)
  • Ban: Permanently ban user
  • Unban: Remove ban
  • Mute: Temporarily restrict user (1 hour default)
  • Unmute: Remove restrictions

How It Works

  1. Each log message includes action buttons
  2. Button callbacks contain user ID and group ID
  3. When admin clicks, bot verifies admin permissions
  4. Bot executes action immediately
  5. Button updates to show action taken

Moderation System

Flood Detection

Tracks message count per user in a time window. When limit exceeded, takes configured action.

Raid Detection

Tracks join count in a time window. When limit exceeded, takes configured action (lock group, ban new joins, etc.).

Filter System

Word Filtering

Scans message text for blacklisted words. Case sensitivity and action are configurable.

Link Filtering

Extracts links from messages and checks against filter rules. Supports allow/deny/whitelist modes.

See Also