Features Overview

Real-time Event Forwarding

• Player Join/Leave — Instant notifications with online player count
• First Join Detection — Special welcome messages for new players
• Chat Monitoring — All in-game chat forwarded to Telegram with HTML formatting
• Death Tracking — Detailed death messages including killer information
• Advancement System — Player achievement notifications (recipe unlocks filtered out)
• World Monitoring — Dimension change tracking (Overworld, Nether, End, custom worlds)
• Command Logging — Monitor command executions with configurable filtering
• Server Start/Stop — Notifications when the server starts or shuts down

Telegram Integration

• Two-Way Chat — Send messages from Telegram directly to Minecraft
• Forum Thread Support — Organize messages in Telegram forum topics
• Remote Server Commands — Execute any server command via /sudo with full output capture
• Server Status — Check server status, TPS, memory, and online players from Telegram
• Admin System — Register Telegram admins with persistent storage
• HTML Formatting — Rich message formatting with bold, italic, code blocks, and blockquotes

Protection and Reliability

• Anti-Flood — Rate limiting prevents message flooding in both directions
• Config Auto-Restore — Corrupt config files are backed up and automatically regenerated
• Chat Filtering — Block unwanted words with admin notifications
• Sudo Blacklist — Prevent dangerous commands from being executed remotely
• Duplicate Message Prevention — Polling guard eliminates message duplication

What's New in v5.0.0

Bug Fixes

• Fixed duplicate Telegram messages — Messages from Telegram were sometimes delivered 2-3 times to Minecraft. Root cause was overlapping long-poll requests. Fixed with an atomic polling guard.
• Fixed /sudo command crashes — The sudo command would crash in non-forum groups because it tried to access message_thread_id even when it didn't exist. Now handles missing thread IDs gracefully.
• Fixed /sudo not showing output — Previously, /sudo plugins would say "executed successfully" but show no output. Now captures and displays full command output in Telegram.
• Fixed multi-line message prefix spam — Multi-line messages from Telegram had the plugin prefix prepended to every line. Now the prefix is applied only once.
• Fixed HTML entity corruption — HTML entities like < were being corrupted by the color code stripper. Now HTML entities are preserved correctly through the entire message pipeline.
• Fixed /reload causing Telegram message flood — Using /reload from Telegram caused an infinite loop. Reload is now only available in-game.
• Fixed /sudo crashing with vanilla commands — Now uses console sender with logger capture for reliable command output.
• Fixed chat mention plugin garbage in Telegram — Plugin-injected component tags are now cleaned before forwarding.

New Features

• Server Start/Stop Notifications — Get notified in Telegram when your server starts or stops
• First Join Detection — Special welcome messages for players joining for the first time
• Anti-Flood System — Configurable rate limiting prevents message flooding
• Sudo Output Capture — /sudo commands now show their full output in the Telegram response
• Sudo Blacklist — Block dangerous commands (stop, op, ban-ip, etc.) from remote execution
• TPS Command — Check server TPS and memory usage from Telegram with /tps
• Config Auto-Restore — If your config becomes corrupt, the plugin automatically backs it up, creates a fresh config, and migrates recoverable values
• Prefix Replacements — Map ugly in-game rank prefixes to clean text for Telegram messages via prefix_replacements config
• Prefix/Suffix Placeholders — New %prefix% and %suffix% placeholders extract rank tags from player display names
• Chat Component Cleaning — Automatically strips plugin-injected component tags from chat messages

Code Improvements

• Full code restructuring — Monolithic 3000-line file split into 11 focused classes across 6 packages
• Clean architecture — Separated concerns: config, telegram API, event handling, commands, data management
• Better error handling — Graceful failure instead of silent crashes
• HTML escaping — User input is properly escaped to prevent HTML injection in Telegram messages

Requirements

• Java 8 or newer
• Spigot or Paper 1.16.x - 1.21.x
• Telegram Bot Token (from @BotFather)
• Telegram Chat ID (group or channel numeric ID)
• Thread ID (only if using forum topics)

Installation Guide

Step 1: Download and Install

1. Download the latest TelegramLogger-5.0.1.jar from Releases
2. Place the .jar file in your server's plugins/ folder
3. Start the server once to generate the default configuration
4. Stop the server to edit the configuration

Step 2: Create a Telegram Bot

1. Open Telegram and find @BotFather
2. Send /newbot and follow the prompts
3. Copy the API Token that BotFather gives you (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

Important Bot Settings (send these to BotFather):
(Optional) Set bot commands for a nice command menu:
Step 3: Get Your Chat ID

1. Create a Telegram group (or use an existing one)
2. Add your bot to the group as an administrator
3. Add @RawDataBot to the group temporarily
4. Look for "chat":{"id": -123456789} in its response — that number is your Chat ID
5. Remove RawDataBot from the group

For Forum Groups (with topics):
Send a message in the specific topic where you want notifications. RawDataBot will show a "message_thread_id" — that's your Thread ID.

Step 4: Configure the Plugin

Edit plugins/TelegramLogger/config.yml:
Save the file and run /tl reload in-game, or restart the server.

Register yourself as an admin (required for Telegram commands):
To find your Telegram user ID, send a message in the group with RawDataBot and look for "from":{"id": 123456}.


Configuration Reference

















Commands Reference

In-Game Commands
All commands require the telegramlogger.admin permission (default: op).

Command	Alias	Description
/telegramlogger reload	/tl reload	Reload configuration from disk
/telegramlogger start	/tl start	Start message forwarding
/telegramlogger stop	/tl stop	Stop message forwarding
/telegramlogger stats	/tl stats	View detailed message statistics
/telegramlogger status	/tl status	Show plugin and bot status
/telegramlogger debug	/tl debug	Toggle debug mode
/telegramlogger admin add <id> <name>	/tl admin add <id> <name>	Register a Telegram admin
/telegramlogger admin remove <id>	/tl admin remove <id>	Remove a Telegram admin
/telegramlogger admin list	/tl admin list	List all registered admins
/telegramlogger help	/tl help	Show help message

Telegram Commands
All commands require the sender to be a registered admin.

Command	Description
/status	Show plugin status, features, server info, and memory
/stats	View message statistics with counts and percentages
/players or /online	List online players (up to 20, with admin crowns)
/tps	Show server TPS (1m/5m/15m) and memory usage
/start	Start message forwarding
/stop	Stop message forwarding
/debug	Toggle debug mode
/sudo <command>	Execute a server command (if enabled)
/help	Show available commands

Admin Management

Admins are Telegram users who can:

• Send messages to the Minecraft chat from Telegram
• Use Telegram commands (/status, /stats, etc.)
• Execute server commands via /sudo (if enabled)

Registering an Admin:
Where 123456789 is the Telegram user ID and Steve is a display name.

Removing an Admin:
Listing Admins:
Admin data is stored in plugins/TelegramLogger/admins.json and persists across restarts.

Important: An admin must be both:

1. Registered via /tl admin add
2. A group administrator or creator in the Telegram group

Message Placeholders

Available placeholders vary by message type:

Placeholder	Available In	Description
%player%	All player events	Player username
%displayname%	All player events	Player display name (may include colors)
%prefix%	All player events	Player rank prefix (extracted from display name)
%suffix%	All player events	Player rank suffix (extracted from display name)
%online%	All events	Current online player count
%max%	All events	Maximum player slots
%message%	Chat messages	The chat message content
%command%	Command logging	The executed command
%death_message%	Death messages	Full death message from Minecraft
%advancement%	Advancement messages	Achievement name
%from_world%	World switch	Previous world (with emoji)
%to_world%	World switch	New world (with emoji)
%version%	Server start	Server version string
%name%	Telegram->MC messages	Telegram sender name

HTML Formatting Guide

Telegram supports HTML formatting in messages. Use these tags in your message templates:



Forum Thread Organization

Telegram forum groups (supergroups with topics) let you organize different event types into separate threads:

This keeps your server events organized and easy to navigate.


Statistics and Metrics

The plugin tracks comprehensive statistics:

Metric	Description
Total Messages	All messages sent to Telegram
Join Messages	Player join event count
Leave Messages	Player leave event count
Chat Messages	Chat messages forwarded
Advancement Messages	Achievements forwarded
Death Messages	Death events forwarded
World Switch Messages	Dimension changes forwarded
Filtered Messages	Messages blocked by chat filter
First Join Messages	New player welcome messages
Command Messages	Commands logged
Server Start Count	Number of server starts logged

View statistics:

• In-game: /tl stats — Shows progress bars and percentages
• Telegram: /stats — Shows clean HTML-formatted statistics

Statistics are stored in plugins/TelegramLogger/data.json and persist across restarts.


Config Auto-Restore System

If your config.yml becomes corrupt (invalid YAML, encoding issues, etc.), the plugin automatically:

1. Detects the corrupt file during loading
2. Backs up the broken file as config.yml.broken.<timestamp>
3. Creates a fresh config.yml with all default values
4. Recovers any valid key: value pairs from the broken file
5. Merges the recovered values into the new config

This means you never lose your bot token, chat IDs, or custom messages due to a YAML syntax error.


Architecture

The plugin is organized into clean, modular packages:


Building from Source

Prerequisites:

• Java Development Kit (JDK) 8 or newer
• Apache Maven 3.6+
• Git

Build Steps:
The build process compiles all Java sources against Spigot API 1.16.5, shades Google GSON into the jar (relocated to avoid conflicts), and produces a single self-contained JAR file. The output JAR is ready to use — just drop it in your plugins/ folder.


Troubleshooting









FAQ

Q: Does this plugin work with Paper?
A: Yes! TelegramLogger works with any Spigot-based server including Paper, Purpur, and forks.

Q: Can I use this with multiple Telegram groups?
A: The main events go to one group/thread. Command logging can go to a separate group via command_executes_chat_id.

Q: Is the bot token stored securely?
A: The bot token is stored in config.yml on your server. Make sure your server files are properly secured.

Q: How do I find my Telegram user ID?
A: Add @RawDataBot to a group, send a message, and look for "from":{"id": YOUR_ID}.

Q: Can regular players use Telegram commands?
A: No. Only users who are both registered admins AND Telegram group admins can use commands.

Q: Does /sudo have any limitations?
A: Yes — commands in sudo_blacklist are blocked. Output is truncated to 3000 characters. The command runs as console (full permissions).

Q: What happens if Telegram is down?
A: The plugin gracefully handles API failures. Events continue to be tracked locally. Messages are simply not sent until the API is available again.

Q: How much server performance does this use?
A: Minimal. All Telegram communication is asynchronous and runs off the main thread. The anti-flood system prevents excessive API calls.

Q: Can I customize the emoji in world names?
A: Currently, world name formatting is built-in. Custom world names are auto-formatted. You can customize the message templates to add your own emoji.




Contact & Support

• Telegram: @LazizbekDev
• Updates: @LazizbekDev_Blog
• Issues: GitHub Issues
• Source: GitHub Repository