Sunnygram

An async, MTProto-native Telegram client library for user accounts.
The user-side sibling of Moonlygram.

Documentation · Quickstart · Bring your session with you

Sunnygram speaks Telegram's native binary protocol instead of the HTTP Bot API, so it signs in as a person, or as a bot over MTProto, and reaches the whole client API surface. The stack is written here from scratch: crypto, transport, session, update state machine. It is not a wrapper over another library.

Where Moonlygram covers the Bot API, Sunnygram covers everything a real account can do.

Install

pip install sunnygram

No required dependencies. sunnygram[speedups] adds a native AES backend and uvloop, both picked up automatically if present. See performance.

You need an api_id and an api_hash from my.telegram.org.

Example

from sunnygram import Client, filters

app = Client("my.session", api_id=API_ID, api_hash=API_HASH)


@app.on_message(filters.private & filters.text & filters.incoming)
async def echo(client, message):
    await message.reply(f"you said: **{message.text}**")


app.run()

The first run asks for a phone number and a code. Every run after that finds the key in the session file and asks nothing.

async with Client("my.session", api_id=API_ID, api_hash=API_HASH) as app:
    me = await app.get_me()
    await app.send_message("me", f"hello from {me.full_name}")

    async for message in app.get_history("@durov", limit=20):
        if message.has_media:
            await message.download(into=f"{message.id}.bin")

    # Anything unwrapped is one invoke away, typed as what the call answers with.
    from sunnygram.raw import functions
    config = await app.invoke(functions.help.GetConfig())   # -> types.Config

Bring an existing session

imported = sunnygram.read_session("my_account.session")
await sunnygram.adopt_session(imported, "sunny.session")

Session files and session strings both read. The peer cache and any stored file_id come across with the key, and the source file is opened read-only. Bringing a project over.

What it does

Around 260 client methods:

Twenty-one kinds of event, from messages and edits to inline queries, join requests, reactions and presence. Which of them a user account sees and which a bot does.

The stack under it, layer by layer:

Not here: calls above the raw layer, and TLS-disguised MTProxy. Account registration is deliberate and permanent: Sunnygram signs in to accounts that already exist.

Design

• Generated where it is mechanical. TL constructors and the error tree come from a pinned schema, drift-guarded in CI. Friendly types and client methods are written by hand.
• Safe by default. Calls are paced, FLOOD_WAIT is honored automatically, secrets never reach a log or a repr, malformed server data fails closed.
• Correct updates. One state machine owns the counters. Every update is delivered once and in order, or not at all.
• Never silent. Everything the library survives on your behalf goes to the sunnygram logger, including a handler of yours that raised.
• Never blocked. Cipher calls, the handshake's 2048-bit arithmetic and SRP's PBKDF2 all leave the event loop.
• Conversations natively. answer = await app.ask(chat, "What is your name?"), with no state machine in between.
• Plugins. app.load_plugins("plugins") registers every decorated handler in a package.

Rights are said the readable way round, which Telegram's own flags are not. Text is markdown unless you say otherwise, HTML if you ask, and offsets are counted in UTF-16 the way Telegram counts them.

Status

Stable. The protocol stack, the client surface and the documentation are in place. ARCHITECTURE.md has the layer stack and the numbered rules the code is held to.

Over 2200 offline tests, mypy --strict across the package, and a scripted MTProto server that completes a real handshake, plus a live tour against a real account covering sign-in, the read surface and a file round trip.

Runnable examples in examples/, each against a real account: login.py signs in and keeps the session, tour.py walks the client surface, echo.py answers anybody who writes to you, files.py round-trips a file, adopt.py takes over a session from elsewhere, ask.py holds a conversation, buttons.py is a bot with a menu, events.py answers inline queries and greets joiners, and moderate.py, topics.py, shop.py, listen.py, plugin_bot.py and get_config.py.

Development

pip install -e ".[dev]"
ruff check src tests codegen examples
mypy
pytest -q

Tests are offline. No account, no credentials, no network.

Two trees are generated and neither is edited by hand:

python codegen/refresh.py --check    # has Telegram shipped a newer layer?
python codegen/gen_tl.py             # rebuild raw/ from the pinned schema
python codegen/refresh.py --errors   # take a fresh error table
python codegen/gen_errors.py         # rebuild the error tree

See CONTRIBUTING.md and SECURITY.md.

License

Mozilla Public License 2.0. See LICENSE. Copyright © 2026 AtarixiaFamine.

File-level copyleft: use Sunnygram in a program of any licence, closed included, and publish changes to Sunnygram's own files under the same one. Your program's code is unaffected.