Telegram Bot Manager

tgbot is a colored command-line manager for any Telegram bot. Point it at a Bot API token and you can inspect the bot, discover chats it has recently seen, send messages, moderate members, manage webhooks, download files, and call every Bot API method.

This is an operator tool. It does not host conversational bot logic.

Requirements

• Python 3.12 or newer
• A bot token from @BotFather

Telegram bot tokens are not scoped. Whoever holds the token can perform every action the bot is allowed to perform in the chats it belongs to.

Install

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -U pip
python -m pip install -e ".[dev]"

Or: make venv && make install.

The console script is tgbot. You can also run python -m tgbot.

Run tgbot with no subcommand for the interactive menu: ↑/↓ to move, Enter to select, q or Esc to quit. j/k work as well.

Authentication

Token resolution order:

1. --token (discouraged — visible in the process list)
2. TELEGRAM_BOT_TOKEN in the environment
3. TELEGRAM_BOT_TOKEN in a .env file in the current directory
4. a hidden interactive prompt

cp .env.example .env
# edit .env — never commit it
tgbot bot info

Write a prompted token to .env (mode 0600):

tgbot --save-env auth check

Use --api-url (or TELEGRAM_API_URL) for a local Bot API server. Non-HTTPS URLs are rejected unless they target localhost.

Chat discovery

The Bot API cannot list every chat a bot was ever added to. There is no getDialogs for bots. tgbot builds a local catalog instead:

tgbot chats discover          # drain getUpdates (~24 hours of pending activity)
tgbot chats listen            # long-poll and keep the catalog fresh
tgbot chats add @mygroup      # register a known username or chat id
tgbot chats list
tgbot chats refresh           # re-fetch getChat for every stored id
tgbot chats export --format json

Catalog files live under $XDG_DATA_HOME/tgbot/<bot_id>/catalog.sqlite (default ~/.local/share/tgbot/).

discover and listen use getUpdates. That is mutually exclusive with a webhook. If a webhook is configured, the command refuses unless you pass --force (which deletes the webhook after confirmation).

Command map

tgbot                  Interactive menu (arrow keys; no subcommand)
tgbot auth             Token status, check, save
tgbot bot              Profile, commands, menu button, default admin rights
tgbot chats            Catalog, settings, invites, join requests, forum topics
tgbot members          Inspect, ban, restrict, promote
tgbot send             Text, media, location, polls, dice, stickers, reactions
tgbot messages         Edit, delete, forward, copy, stop poll
tgbot updates          Webhook get/set/delete, getUpdates, listen
tgbot files            getFile + download
tgbot stickers         Sticker set helpers
tgbot stars            Balance, transactions, refunds
tgbot api METHOD       Raw Bot API call (JSON or --param)

Global flags: --json, --verbose, --quiet, --timeout, --api-url, --yes.

Chat arguments accept a numeric id, @username, or a catalog title. Negative Telegram chat ids start with -; pass -- before them so the shell/CLI does not treat them as flags (tgbot chats show -- -1001234567890).

Cookbook

tgbot bot info
tgbot bot set-name "Support Bot"
tgbot bot set-commands --command "start:Start the bot" --command "help:Show help"

tgbot send text @mychat "Hello from tgbot" --parse-mode HTML
tgbot send photo -- -1001234567890 --file ./photo.jpg --caption "Launch"

tgbot members admins -- -1001234567890
tgbot members ban -- -1001234567890 123456789 --yes

tgbot updates webhook-info
tgbot api getChat --param chat_id=@mychat
tgbot api sendMessage --body '{"chat_id": "@mychat", "text": "hi"}'

Destructive methods (leaveChat, bans, logOut, close, webhook delete) ask for confirmation unless --yes is set. --json mode always requires --yes for those actions so scripts cannot hang on a prompt.

Output

Human output uses Rich tables and panels. Add --json for machine-readable stdout (errors still go to stderr).

Exit codes:

Code	Meaning
0	Success
1	Configuration / usage
2	Telegram API error
3	Network / transport

Development

See CONTRIBUTING.md. Security reporting: SECURITY.md.

make ci

License

MIT