# Paper Telegram Bridge<\/p>\n
A fork from spigot-tg-bridge with some new features.<\/p>\n
<\/p>\n
### This plugin will send chat messages from Minecraft to Telegram, and from Telegram to Minecraft.<\/p>\n
## How to use:<\/p>\n
1. Download .jar file and put it in
\n `plugins\/` directory on your server **OR** clone this repo and run `gradle` inside repo’s directory.<\/p>\n
2. If you already have telegram bot, skip this step. Otherwise, create it through BotFather.
\n You’ll go through step-by-step instructions, give a bot **username** and most importantly, obtain a bot **token**.
\n Save this token for future use. **Note:** in order to make your bot hear raw text messages (not commands), you must
\n disable privacy mode option which is on by default. Go through bot’s
\n settings: **Bot Settings -> Group Privacy** and click **Turn Off**.<\/p>\n
3. Next, you need to tell plugin about your new bot. You can either:<\/p>\n
– Run Paper server, plugin will log `”No config file found! Saving default one.”`. After that, stop server and
\n proceed to 4th step.
\n – Copy config.yml
\n to `plugins\/PaperTelegramBridge\/` in your server directory.<\/p>\n
4. A `config.yml` is just a valid YAML file, alternative for JSON, but more
\n human-readable.
\n Now, take bot’s **token** which you got in 2nd step and paste them into `config.yml`, so it looks like this:<\/p>\n
“`yaml
\n botToken: abcdefghijklmnopq123123123
\n # other configuration values…
\n “`<\/p>\n
5. Run Paper server.<\/p>\n
6. Add you bot to chats, where you plan to use it. In each of them, run `\/chat_id` command. The bot should respond and
\n give special value – **chat id**. Now, open `config.yml` and paste this ID under `chats` section, so it will look
\n like this:<\/p>\n
“`yaml
\n botToken: abcdefghijklmnopq123123123
\n chats: [
\n -123456789,
\n 987654321,
\n # other chat id’s…
\n ]
\n “`<\/p>\n
7. (Optional) To enable admin commands like `\/whitelist`, you need to add Telegram user IDs to the `admins` list in `config.yml`.<\/p>\n
“`yaml
\n admins: [
\n 123456789,
\n 987654321,
\n # other admin user ids…
\n ]
\n “`<\/p>\n
8. You can extend `config.yml` with more tweaks, which are described in the table below, but it’s not necessary, plugin
\n will use default values instead, if they’re missing. Also, check out the [example](src\/main\/resources\/config.yml).<\/p>\n
9. Re-run server or type `tgbridge_reload` into server’s console.<\/p>\n
## Plugin configuration:<\/p>\n
| Field | Description | Type | Required | Default | ## Telegram bot commands:<\/p>\n Commands are customizable through config. If command doesn’t exist in config, it will be disabled<\/p>\n | Command | Description | ## Format string:<\/p>\n “` This command is only available to users listed in the `admins` configuration field. The plugin will also send notifications when players try to join but are kicked due to not being whitelisted (configurable via `logWhitelistKick`).<\/p>\n ## Minecraft assets<\/p>\n In this repository won’t include the minecraft icons required to build the plugin for the inventory and advancements rendering features. “` Some icons, like potions, require renaming. The resulting .png files need to be placed `src\/main\/resources\/textures`.<\/p>\n","protected":false},"excerpt":{"rendered":" Connect Telegram chats and Minecraft servers seamlessly.<\/p>\n","protected":false},"featured_media":119301,"template":"","meta":{"_minecraft_slug":"paper-telegram-bridge","_minecraft_project_id":"HhD6VFrX","_minecraft_author":"pbl0","_minecraft_license":"GPL-3.0-only","_minecraft_downloads":537,"_minecraft_follows":5,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"paper-telegram-bridge.zip","_minecraft_size_bytes":83532066,"_minecraft_version_count":12,"_minecraft_updated_at":"2026-05-16T10:30:47.424742Z","_minecraft_date_created":"2025-02-04T23:23:26.202836Z","_minecraft_date_modified":"2025-10-25T15:04:05.766049Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/paper-telegram-bridge","_minecraft_icon_attachment_id":119301,"_minecraft_imported_at":"2026-06-07T00:24:14+00:00","_minecraft_import_hash":"09fdf3f3384598b2c8896d5917648bf3","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[126,127,867,92],"mod_loader":[132],"minecraft_version":[40,41,38,78,79,80,81,82],"class_list":["post-119300","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-management","mod_category-paper","mod_category-social","mod_category-utility","mod_loader-paper","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n| :——————–: | :———————————————————————————————– | :——————–: | :—————-: | :———————-: |
\n| enable | If plugin should be enabled | `boolean` | :x: | `true` |
\n| botToken | Telegram bot token (How to create bot) | `string` | :heavy_check_mark: | – |
\n| chats | Chats, where bot will work (to prevent using bot by unknown chats) | `number[] or string[]` | :heavy_check_mark: | `[]` |
\n| admins | List of Telegram user IDs authorized to use admin commands like `\/whitelist` | `number[] or string[]` | :x: | `[]` |
\n| serverStartMessage | What will be sent to chats when server starts | `string` | :x: | `’Server started.’` |
\n| serverStopMessage | What will be sent to chats when server stops | `string` | :x: | `’Server stopped.’` |
\n| logJoinLeave | If true, plugin will send corresponding messages to chats, when player joins or leaves server | `boolean` | :x: | `true` |
\n| logFromMCtoTG | If true, plugin will send messages from players on server, to Telegram chats | `boolean` | :x: | `true` |
\n| logFromTGtoMC | If true, plugin will send messages from chats, to Minecraft server | `boolean` | :x: | `true` |
\n| logPlayerDeath | If true, plugin will send message to Telegram if player died | `boolean` | :x: | `false` |
\n| logPlayerAsleep | If true, plugin will send message to Telegram if player fell asleep | `boolean` | :x: | `false` |
\n| logPlayerAdvancement | If true, plugin will send message to Telegram if player gets an advancement | `boolean` | :x: | `true` |
\n| logInventory | If true, plugin will send image of inventory, item or ender chest [Read more](#Inventory) | `boolean` | :x: | `true` |
\n| logWhitelistKick | If true, plugin will send notification when a player is kicked due to not being whitelisted | `boolean` | :x: | `true` |
\n| strings | Dictionary of tokens – strings for plugin i18n | `Map
\n| commands | Dictionary of command text used in Telegram bot | `Map
\n| telegramMessageFormat | Format string for TGtoMC chat message | `string` | :x: | See default config |
\n| minecraftMessageFormat | Format string for MCtoTG chat message | `string` | :x: | See default config |
\n| silentMessages | Disable notification in Telegram chats | `boolean` | :x: | false |
\n| apiOrigin | Use different API endpoint for the bot | `string` | :x: | https:\/\/api.telegram.org |
\n| disableConfigWatch | Do not watch the config for changes | `string` | :x: | false |<\/p>\n
\n| :———-: | :————————————————————————————- |
\n| `\/online` | Get players, currently online |
\n| `\/time` | Get time on server |
\n| `\/chat_id` | Get current chat ID (in which command was run) for config.yml |
\n| `\/whitelist` | (Admin only) Manage server whitelist – list whitelisted players or add\/remove a player |<\/p>\n
\n+——–+ >–minecraftMessageFormat(message)-> +————–+
\n| Paper | | Telegram bot |
\n+——–+ <--telegramMessageFormat(message)--< +--------------+\n```\n\nApplies to `telegramMessageFormat` and `minecraftMessageFormat` configurations.\nMust contain `%username%` and `%message%` inside.\nYou can customize message color with it (coloring works only for `telegramMessageFormat`). You can customize\nbold\/italics\/strikethrough formatting (works only for `minecraftMessageFormat`).\nSee Minecraft message color codes\nand Telegram message formatting for more information.\nThis feature is related to this issue\n\n## Plugin commands:\n\n| Command | Description |\n| :---------------: | :----------------------------------------------------------------------------------------- |\n| `tgbridge_reload` | Reload plugin configuration w\/o need to stop the server. Works only through server console |\n\n## Permissions\n\n| Permission | Description |\n| :-------------------------: | :------------------------------------------------------------------------------------------------------------------------------------ |\n| `tg-bridge.silentjoinleave` | When set to **true** the bot won't send join and leave messages for that player. It will also be hidden from the **\/online** command. |\n\n## Inventory\n\nSimilar behavior as InteractiveChat plugin (not a dependency!).\nCommands implemented:\n\n- [inv]\n- [item]\n- [ender]\n\n## Whitelist Management\n\nServer admins can manage the whitelist directly from Telegram using the `\/whitelist` command:\n\n- `\/whitelist` - List all whitelisted players\n- `\/whitelist
\nThis icons can be generated using the mod IconExporter and running in-game this command:<\/p>\n
\n\/iconexporter export 64
\n“`<\/p>\n