ZomBot Checker

A lightweight Telegram bot that monitors and maintains your Project Zomboid server.

---

Telegram bot to monitor your Project Zomboid server

ZomboidScript-V2 is a lightweight automation companion for running a Project Zomboid server, designed to make server maintenance easier and more predictable.

Instead of constantly checking logs or worrying about mod updates breaking the server, this tool acts as a small watchdog that keeps an eye on your server and communicates with you through Telegram.

The bot connects to the server using RCON, performs regular health checks, and reads server logs to detect when Workshop mods require updates. If an update is detected, it can warn players in-game, give them time to finish what they are doing, and safely restart the server so everything stays compatible and stable.

Through Telegram, administrators can monitor the server, see who is online, and run maintenance actions without needing direct access to the server machine.

---

Usage

1. Generate a bot token with @BotFather in telegram
2. Edit config.ini with your Project Zomboid server information
   (Supports rented servers such as Bisect Hosting)
3. Start the bot and open it in Telegram
4. The first person who runs /claimowner becomes the owner (if you have problem with this edit users.json and put your ID on owner and restart the bot)
5. Optionally invite admins using /addadmin
6. The bot will monitor the server and notify admins when something requires attention such as if the server is offline for a long time or notifications of the updates

---

Features

Telegram-based monitoring

Monitor your Project Zomboid server directly from a private Telegram chat.

Server status and player visibility

Uses RCON to check if the server is responding and to list connected players.

Automatic mod update detection

Runs the built-in mod update check through RCON and analyzes server logs through SFTP to detect when mods require updates.

Safe restart workflow

When updates are detected, the bot can warn players and coordinate a safe restart instead of leaving the server running outdated mods.

Owner and admin roles

Supports an owner/admin permission model, allowing trusted admins to monitor the server without exposing full credentials.

Invite-based admin access

Admins are added through temporary invite codes, keeping the bot private even if the bot account is publicly visible.

Configurable monitoring intervals

Heartbeat and mod-check intervals can be adjusted in config.ini.

Localization support

Includes English and Spanish language files in the locales/ folder.

Lightweight and self-hosted

Runs as a simple Python script with minimal dependencies.

Compatible with hosted servers

Designed to work even on rented servers where only RCON and SFTP access are available.

---

How it works (Simple Overview)

• Connects via RCON to check server status and players
• Checks for mod updates using RCON + server logs (Yes this would be more easy if the RCON responded with the actual mods status instead of writing the answer on the logs)
• Sends Telegram notifications to admins and the owner
• Can restart the server safely when updates are required (uses /servermsg to alert players currently on the server)
• Allows the owner to invite admins to monitor the server

---

Important Notes

• Configure config.ini before running the bot
• Commands only work in private chat
• Monitoring intervals are configurable in config.ini
• Language files are located in:
  • locales/en.json
  • locales/es.json

---

Available Commands

The bot uses a simple permission system:

• Owner – Full control of the bot and server maintenance actions
• Admin – Monitoring access and basic server information
• Public – Limited commands used to register or identify yourself

All commands must be used in private chat with the bot.

Command	Permission	Description
/start	Public	Shows a welcome message and basic information about the bot.
/help	Public	Displays the list of available commands.
/whoami	Public	Shows your Telegram user ID and your detected role (owner, admin, or unknown).
/claimowner	Public (first use only)	Claims ownership of the bot. The first user who runs this becomes the owner.
/redeem CODE	Public	Redeems an admin invitation code generated by the owner.
/status	Admin / Owner	Displays the current server status and recent activity information.
/players	Admin / Owner	Shows the list of currently connected players.
/lastseen	Admin / Owner	Shows the last time the server responded to a heartbeat check.
/servermsg CUSTOMTEXT	Admin / Owner	Sends a custom in-game server message via RCON.
/checkmods	Admin / Owner	Manually checks if mods require updates.
/addadmin	Owner	Generates a temporary invitation code to add a new admin.
/listadmins	Owner	Shows the current list of admins and pending invite codes.
/deleteadmin ID	Owner	Deletes an admin by numeric Telegram ID.
/hardreset	Owner	Clears admins and pending invite codes (keeps owner). Requires confirmation.
/forcerestart	Owner	Sends save + quit immediately to trigger a restart.
/cancel	Owner	Cancels a pending action such as a restart confirmation.

---

Run

Install dependencies:

pip install -r requirements.txt