TDelegram — a full-featured Telegram client (library + CLI)

TDLib exposes 1022 functions through a single JSON interface. TDelegram covers all of them on day one through one generic transport, with ergonomics, normalization, safety, errors and docs on top. No MCP layer: an importable Python library plus a tdelegram CLI.

What it is for

• Where Telegram is blocked — proxy add takes a shared tg://proxy, t.me/proxy or socks5:// link and works before login, which is when it is needed.
• Catching up without being seen to — inbox lists unread messages across chats and marks nothing read; draft set leaves a reply for you to send.
• Backups and research — chat export is resumable and incremental, with media where the chat allows saving it; records carry views, forwards, reactions and where a forward came from.
• Taking your words back — msg delete-mine removes your own messages in a chat for everyone, after showing how many.
• Alerts — watch streams new messages matching words, a pattern, a chat or a sender.
• Reading without seeing or hearing — --format text gives screen readers plain sentences, and msg transcribe turns a voice message into text.

Install

TDLib is a C++ dependency with no distribution package, so installing it natively means a ~20 minute compile on Linux. Docker is the short way in — the image has TDLib already built.

Published for linux/amd64 and linux/arm64:

docker pull ghcr.io/bulanovdm/tdelegram:latest

# The session lives in /session; mount it or every run starts logged out.
docker run --rm -i -v "$HOME/.tdelegram:/session" \
  ghcr.io/bulanovdm/tdelegram auth status

Which tag to pull — a pinned release, the newest one, or unreleased main — and when each moves is in RELEASING.md.

Global flags such as --yes go before the command. One alias makes every command in this README work verbatim:

alias tdelegram='docker run --rm -i -v "$HOME/.tdelegram:/session" \
  -v "$PWD:/work" -w /work -e TELEGRAM_API_ID -e TELEGRAM_API_HASH \
  ghcr.io/bulanovdm/tdelegram'

auth login and destructive commands are the exceptions — they prompt, and a destructive command takes its typed confirmation only from a terminal. A second alias gives them one:

alias tdelegram-tty='docker run --rm -it -v "$HOME/.tdelegram:/session" \
  -v "$PWD:/work" -w /work -e TELEGRAM_API_ID -e TELEGRAM_API_HASH \
  ghcr.io/bulanovdm/tdelegram'
tdelegram-tty auth login

Keep -t out of the first alias: with a terminal attached, Docker merges stderr into stdout, which puts diagnostics in the JSON, and it refuses to start when its input is a pipe.

Native

Preferable on macOS, and the fallback wherever Docker is not available:

brew install tdlib   # macOS
pip install tdelegram

On Linux, build TDLib from source and point TDELEGRAM_TDJSON at the resulting libtdjson.so. Full instructions, including getting an api_id/api_hash and the first login, are in skills/tdelegram/references/setup.md.

Quickstart

tdelegram auth login
tdelegram chat list
tdelegram inbox                                  # unread messages; marks nothing read
tdelegram chat history --chat @durov --limit 5
tdelegram msg send --chat me --text "hi"        # previews
tdelegram --yes msg send --chat me --text "hi"  # performs
tdelegram --yes msg send --chat me --text "*hi*" --parse-mode markdown  # MarkdownV2
tdelegram watch --for 10m                       # new messages as they arrive
tdelegram --format text inbox                   # plain lines, for a screen reader

Where Telegram is blocked, store a proxy before logging in — every proxy command works without a session:

tdelegram --yes proxy add 'https://t.me/proxy?server=...&port=443&secret=...'
tdelegram proxy ping 1 && tdelegram auth login

Library:

from tdelegram.client import TelegramClient
from tdelegram.transport import TdJsonTransport
from tdelegram.config import discover_library
from tdelegram.api import chats, messages

transport = TdJsonTransport(discover_library())
with TelegramClient(transport) as client:
    for chat in chats.iter_list(client, scope="main", maximum=10):
        print(chat["title"])

Using it from an agent

skills/tdelegram/ is an agent skill covering the CLI, the gate and the discipline it implies, reading recipes, the Python API, troubleshooting and installation from scratch. Point a coding agent at skills/tdelegram/SKILL.md, or install the packaged bundle.

Safety

Mutating calls preview and exit; --yes performs them. Destructive calls (deleteChatHistory, banChatMember, logOut, deleteAccount, terminateAllOtherSessions, …) need --yes and the method name typed at an interactive terminal, so a script, a pipe or an agent's shell does not complete one by accident. It is a safeguard, not a sandbox: a program that fakes a terminal can type the name too. The gate lives in TelegramClient.call() — including the raw call escape hatch. See src/tdelegram/methods.json for all 1022 verdicts.

call also checks each request against TDLib's schema before sending it, because TDLib ignores a field it does not recognise and runs the call without it. tdelegram describe <method> shows the real parameters.

Layout

• src/tdelegram/tdjson.py — ctypes, modern C API only
• transport.py / loop.py / client.py — seam, reader thread, facade
• auth.py — 11-state machine with CredentialProvider
• safety.py + methods.json — write gate + registry
• normalize.py / entities.py / dates.py / paging.py / files.py
• api/ — account chats messages media contacts users admin topics folders drafts reactions polls search updates bots stories secret proxies inbox export
• schema.py + schema.json — every TDLib request shape; what call and the tests check against
• cli/ — Typer tree, JSONL on stdout, diagnostics on stderr

Session

Own home at ~/.tdelegram/ (--session-dir overrides). Never commit or copy it: it is full account access. See SECURITY.md.