Heimdall - Protection Bot
Heimdall is a powerful Telegram group management bot designed for crypto communities. It provides comprehensive moderation tools, anti-spam protection, portal verification, custom filters, and integration with various crypto services.
Anti-Spam Protection
Automatic detection and removal of spam messages, fake admins, scammers, and prohibited content. Includes OCR-based text extraction from images and videos to detect spam hidden in media.
Portal Verification
Secure entry system requiring users to verify through a web portal before joining groups. Collects device fingerprints to detect alt accounts of banned users.
Custom Filters
Create automatic responses to keywords or phrases. Supports single words and multi-word phrases in quotes.
Crypto Integration
Track token prices, market caps, holders. Integration with DexScreener, PumpFun, and various buy bots. Supports Solana, Ethereum, TON, and BSC tokens.
Automatic Whitelisting
Users are automatically whitelisted after sending 10 safe (non-spam) messages, exempting them from further anti-spam checks without admin intervention.
Image & Video Text Detection
Uses OCR technology to extract and scan text from images, videos, GIFs, and documents for spam content - catching scammers who hide messages in media.
Whales Mode
Restrict chat to verified token holders based on minimum holding requirements. Users verify by connecting their wallet on-chain.
Referral Contests
Create and manage referral competitions with automatic tracking and leaderboards. Each user gets a unique invitation link to share.
Moderation Commands
Ban & Unban
Ban a user from the group. Can be used by replying to a message, mentioning a user, or providing a UserID.
Unban a previously banned user, allowing them to rejoin the group.
Mute & Unmute
Mute a user, preventing them from sending messages. Optional duration (e.g., 1h, 1d, 1w). Without duration, mute is permanent until unmuted.
Unmute a user, restoring their ability to send messages. Resets their deleted message counter and removes pending verifications.
Message Management
Delete the replied-to message.
Report a user or message to group admins. Creates a report record and notifies admins with ban/mute buttons.
Lock the chat, preventing all non-admin members from sending messages. Shows confirmation buttons.
Unlock the chat, allowing all members to send messages again. Shows confirmation buttons.
User Management
Manually whitelist a user, exempting them from anti-spam checks and automatic moderation. Resets their deleted message counter. Note: Users are also automatically whitelisted after 10 safe messages (see Automatic Whitelisting).
Exclude yourself (or a specified user if admin) from the /all mention feature.
Scan and remove all deleted Telegram accounts from the group.
Get detailed information about a user including: permban status, report count, mute count, ban count, whitelist status, verification status, and recent deleted messages.
View all reports filed against a specific user, including both message content and reasons.
Inactive User Management
Get count of users who haven't sent a message in X days (default: 7 days).
List inactive users with their UserID, days since last message, and total message count. Shows first 50 users.
Warn inactive users by mentioning them. Users who don't respond within 1 hour will be automatically removed. Skips admins and whitelisted users.
Filter Commands
How Filters Work
Filters create automatic responses when specific keywords or phrases are detected in messages.
Single-word filters: Match when used as a command (e.g., typing "ca" or "/ca" triggers the filter)
Multi-word filters: Match when the phrase appears ANYWHERE in a message (case-insensitive)
Create a new filter. For single words, the word becomes a trigger command. For multi-word phrases, wrap in quotes - it will match anywhere in messages.
Examples:
/filter website https://example.com -
Triggers on /website or website
/filter "when moon" Soon! Keep holding! -
Triggers whenever "when moon" appears in any message
Display all active filter keywords/phrases for the group.
Remove a specific filter by its keyword.
Remove ALL filters from the group. Use with caution!
Special Filter: CA
Setting a filter with keyword "ca" or "/ca" will also
automatically set the group's contract address, enabling
the /mcap command and other crypto
features.
Configuration Commands
Main Configuration
Open the main configuration menu. Provides access to: Portal setup, Welcome Messages, Filters, Whales Mode, Voting campaigns, Lounge Mode, and all other group settings.
Display list of all group administrators with their
roles. Can be disabled via /adminslist off.
Feature Toggles
Toggle silent mode. When enabled: removes ads, hides ban/mute notification messages, and suppresses bot action notifications for a cleaner chat experience. Premium feature with payment option.
Enable/disable joke mode. When enabled, the /sol command will first show a fake price before revealing the real one.
Enable/disable the /meme command for the group.
Enable/disable the /admins command for regular users.
Crypto Tools
Price & Market Data
Get the current SOL/USD price from PumpFun API.
Get market cap and holder count for a token. Without argument, uses the group's set CA. Supports Solana, Ethereum, TON, and BSC tokens.
Set or display the group's contract address. When set, enables various crypto features like /mcap without arguments.
Voting & Trending
Display all available voting buttons for the group's token. Automatically detects which buy bots are installed (Skeleton, Major, WTF, etc.) and shows relevant voting links.
Start a community-funded rank boost campaign for DEX trending.
Start a community-funded volume boost campaign.
Start a FREE PumpFun bump bot campaign.
Stop an active rank boost campaign. Donated SOL will be refunded.
Stop an active volume boost campaign. Donated SOL will be refunded.
Stop an active bump bot campaign.
Bot Integration
Get instructions for adding the Skeleton Price Bot (@skeletonpricebot) to your group.
Get instructions for adding the Freya Raid Bot (@Freya_raid_bot) to your group.
Get link to Odin Tools - Volume Bot, Rank Bot, FREE PumpFun Bump Bot, DEX Emoji and more.
Utility Commands
Communication
Mention all members in the group. Shows confirmation dialog first. Members can exclude themselves using /exclude. Automatically bans permabanned users detected during the process.
Entertainment
Get a random crypto-themed joke. Only works if jokes are enabled for the group.
Get a random meme (image or video). Memes are sourced
from 9GAG across multiple categories including humor,
crypto, and classic memes. Videos are automatically
converted for Telegram compatibility. Only works if
memes are enabled for the group (toggle with
/memes on|off).
Statistics
View group statistics including bans, mutes, removed users, etc.
View global Heimdall statistics across all protected groups.
Display help information and command overview.
Referral Contests
View current referral contest leaderboard or create a new contest (if admin). Each user receives a unique cryptographically-generated invitation link to share. When someone joins through the link, it is automatically tracked and counted toward the referrer's score. Contests support start/end dates, prize descriptions, and real-time leaderboards.
DM Commands
These commands work when messaging the bot directly in private chat.
User Information
Same as group /info but available in DM. You can also forward a message from a user with hidden identity to automatically resolve who they are.
Get information about who installed Heimdall in a specific group.
View all reports for a user (works same as in groups).
Group Configuration via DM
Add filters via DM when configuring a group through the bot. Works same as in-group /filter command.
Remove a filter via DM when configuring a group.
Remove all filters via DM when configuring a group.
Automatic Features
These features run automatically in the background without requiring any commands. They are always active and protect your group 24/7.
Automatic Whitelisting
Heimdall tracks every message a user sends in a group. After a user posts 10 safe messages (messages that don't trigger any spam detection), they are automatically whitelisted for that group.
What "safe messages" means: Only messages that pass all spam checks count toward the threshold. Messages flagged as spam, containing prohibited content, or matching banned patterns do not count.
- Threshold: 10 safe messages per group
- Scope: Each group tracks counts independently - joining a new group starts a fresh count
- Benefit: Whitelisted users are exempt from anti-spam checks, making the experience seamless for legitimate members
- Automatic: No admin action required - it happens silently in the background
- Exemptions: Admins and already-whitelisted users are always exempt from spam checks regardless
Image & Video Text Recognition (OCR)
Heimdall uses OCR to extract text from media sent in chat. This prevents scammers from bypassing text-based filters by putting their spam inside images or videos.
- Image processing: Images are converted to grayscale with automatic level and contrast enhancement for maximum OCR accuracy
- Video processing: Heimdall extracts the middle frame of a video (for best content representation) and runs OCR on it
- Fallback logic: If no text is found in the initial scan, additional frames are extracted and scanned
- Spam checking: All extracted text is combined with the message text and checked against the full spam detection ruleset
Supported formats: JPG, PNG, WebP, GIF, BMP, MP4, AVI, MKV, WebM, MOV, WMV, FLV, and more.
Spam Detection
Over 200 spam patterns are actively checked against every message. The system uses text normalization to defeat evasion techniques.
| Detection Type | Description |
|---|---|
| Banned Words | Messages containing known spam phrases from a maintained word list |
| Scam Patterns | "Contact me if you hold X", fake wallet/payment scams, rug pull indicators, phishing attempts |
| Fake Admins | Users impersonating admins via similar names, titles like "CEO", "Dev", or "Owner", or matching the group/token name |
| Fake Contracts | Users with blockchain addresses in their display names to trick others |
| Fake Bots | Impostor bots using homograph/lookalike characters in usernames (e.g., capital "I" instead of "l") |
| Text Normalization | Cyrillic-to-Latin conversion, Unicode mapping, and number-to-letter substitution (0→O, 1→I) to catch evasion tricks |
| Image Hash Matching | Perceptual image hashing (DifferenceHash) detects copied or slightly modified spam images, even after cropping or color changes |
| Similar Name Detection | Levenshtein distance algorithm catches names visually similar to admin names or the group name |
Portal Verification
New users must verify through a web portal before accessing the group. The portal serves two purposes: confirming the user is human, and collecting device fingerprint data for alt account detection.
The portal supports customizable welcome text, an image, and inline buttons. Users who don't verify within the configured time receive reminders.
Permban Propagation
When a user is permanently banned, the ban is enforced across ALL Heimdall-protected groups. This creates a network-wide defense against persistent bad actors.
Alt Account Detection: If a permabanned user creates a new Telegram account, Heimdall detects it through fingerprint matching during portal verification and automatically bans the alt account as well.
Link Security
Heimdall automatically checks links posted in chat for safety:
- Safe domain whitelist: Configurable list of trusted domains (cached with regular updates)
- Redirect chain following: Follows shortened URLs (bit.ly, t.co, tinyurl.com, etc.) to check the final destination
- Pattern matching: Regex patterns detect phishing, malware, and scam content on linked pages
- 404 detection: Links returning 404 errors are flagged as dangerous
- Re-checking: Previously checked URLs are re-validated every 7 days
Whales Mode
When enabled, Whales Mode restricts chat to verified token holders who meet a minimum holding requirement.
How verification works:
- Admin enables Whales Mode and sets the minimum token holding requirement
- Users verify by sending 1 token to the Heimdall verification wallet
- Users can verify multiple wallets
- Heimdall checks holdings every 30 minutes
Behavior:
- Users who fall below the minimum are automatically muted with a notification
- If a previously qualified user sells their tokens, they receive a different message indicating their holdings dropped
- Users are automatically unmuted when holdings are restored
- Notifications have a 24-hour cooldown to prevent spam
- Admins and whitelisted users are always exempt
Welcome Messages
Customizable welcome messages greet new users when they join the group.
- Custom text: Set any welcome message text
- Image: Optionally include an image with the welcome message
- Inline buttons: Add clickable buttons (e.g., links to website, socials, rules)
- Toggle: Can be enabled or disabled per group via the /config menu
Other Features
Lounge Mode
When enabled, relaxes certain spam checks to allow forwarded messages and channel posts without triggering moderation. Useful for groups that regularly share content from other channels or sources. Toggle through the /config menu.
Message Tracking
Heimdall keeps a history of up to 30 messages per user per group. Deleted messages are preserved in the tracking system, and administrators can view a user's recent deleted messages via the /info command for evidence in moderation decisions.
New User Monitoring
Newly joined users are closely monitored with stricter scrutiny until they build up a history of safe messages and become auto-whitelisted. Users with pending verifications receive reminders to complete the process.
Inactive User Warnings
When admins trigger /kickinactive, inactive users receive a warning mention. If they don't respond within 1 hour, they are automatically removed. Admins and whitelisted users are always exempt.
CA Auto-Detection
Automatically detects blockchain contract addresses posted in chat and tracks them for analytics purposes.
Silent Mode
When enabled, removes ads and hides ban/mute notification messages from chat for a cleaner experience. Available as a premium feature via the /silentmode command.