How I monitor my Telegram userbots with zero infra

ANIS — Tue, 09 Jun 2026 16:58:16 +0000

I run a few Telegram bots and userbots in production. A couple of aiogram bots, a couple of Telethon userbots doing scraping work. For months I kept hitting the same two failures.
First: a bot dies and I don't notice. The process crashes or hangs, and I find out hours later when someone tells me it stopped answering.
Second, and worse: a userbot account gets restricted or banned. Telegram throttles it, or kills the session, and by the time I look the damage is done.
The obvious answer is monitoring. But every option felt wrong for the size of the problem. Prometheus plus Grafana for two bots is a lot of moving parts to babysit. Hosted observability wants a server, an agent, a dashboard. I just wanted a Telegram message when something broke.
So I built tgwatch.

What it does
You attach it to your bot or userbot in two lines. After that, capture is automatic:

alive or dead state, based on a heartbeat
message, error, and FloodWait counters
userbot account health: restricted, banned, or dead session

When something degrades, a separate watchdog process sends you a Telegram alert.
from tgwatch import Watch

watch = Watch(
storage="tgwatch.db",
alert_bot_token="123456:abc...", # a Telegram bot dedicated to alerts
alert_chat_id="@my_alerts",
)

Telethon userbot

watch.attach(telethon_client, kind="userbot", name="scraper")

aiogram bot

watch.attach(dispatcher, kind="bot", name="support_bot")
After attach, you write no more monitoring code. Your bot behaves exactly as before. Exceptions are recorded, then re-raised, so nothing changes about how your code runs.

The part I couldn't find elsewhere
Knowing a process is up is easy. Knowing a userbot account is healthy is not.
A Telethon userbot can be technically running while its account is restricted or already banned. The process looks fine. The account is dead.
tgwatch classifies account state from two sources.
Passive layer: it reads the Telethon exceptions your code already throws.

ExceptionState
PeerFloodErrorrestricted
PhoneNumberBannedError, UserDeactivatedBanErrorbanned
AuthKeyUnregisteredErrordead session
FloodWaitErrorfloodwait event (slowed down, not a degraded state by itself)

Active layer: a periodic get_me() probe that reads the account's restricted flag.
The two signals merge with a worst-state-wins rule: banned beats dead session beats restricted beats healthy. A "banned" signal is never overwritten by a later unconfirmed "healthy". So once tgwatch sees a ban, it stays loud.

Why a separate process
A dead process can't alert you about itself. That sounds obvious, and it's the reason the watchdog runs on its own.
tgwatch watch --storage tgwatch.db --token 123456:abc... --chat-id @my_alerts
The watchdog reads the shared SQLite file, detects degraded states and missed heartbeats, and sends the alert. Your bot writes state into SQLite. The watchdog reads it. If the bot dies, the watchdog is still there to notice.
You can also check state by hand:
tgwatch status --storage tgwatch.db
NAME KIND STATUS HEALTH MSG ERROR FLOODWAIT
scraper userbot up restricted 842 3 1
support_bot bot down n/a 1503 12 0

Design choices I stand by
Zero runtime dependencies in the base install. The core uses only the standard library: sqlite3, urllib, argparse. aiogram and telethon are optional extras, imported lazily. If you only run bots you never install Telethon, and the reverse.
One direction of dependencies. There's a core layer that knows nothing about Telegram. Adapters depend on core, never the other way. SQLite runs in WAL mode, so the bot process and the watchdog process share the file safely.
Secrets never touch the database or the logs. Bot token, session string, phone number: all masked at the recorder, with sensitive keys redacted and a regex for bot-token shapes. I didn't want a monitoring tool to become the thing that leaks the credentials it's supposed to protect.
Alerting fails soft. Sending an alert retries with backoff, then logs and gives up. It never raises into the bot you're monitoring. A monitoring tool that crashes your bot is worse than no monitoring.
The whole thing has 241 tests at 96% coverage and runs fully offline.

Where it's at
tgwatch is at 0.1.0. It does what I needed, and I'm running it on my own bots now.
pip install "tgwatch[telethon,aiogram]"
Repo: https://github.com/assinscreedFC/tgwatch
What I'd like feedback on: the account-health signals. Telethon throws a lot of exceptions, and I mapped the ones that bit me. If you've seen account states I'm not catching, tell me.

DEV Community: ANIS

How I monitor my Telegram userbots with zero infra

Telethon userbot

aiogram bot