Moonlygram

A modern, async Python framework for the Telegram Bot API, with built-in rich messages.
Pure HTTP. No MTProto. No native dependencies.

Description

Moonlygram is an asynchronous framework for the Telegram Bot API. A Bot holds the API methods and an Application (moonlygram.ext) registers handlers and runs the update loop, so the shape feels familiar if you have used python-telegram-bot. On top of that, it adds something no other library has: rich messages (Bot API 10.3).

Installation

pip install moonlygram

Requires Python 3.10 or newer.

Usage

from moonlygram import InlineKeyboardButton, InlineKeyboardMarkup
from moonlygram.ext import Application, CallbackQueryHandler, CommandHandler


async def start(update, context):
    keyboard = InlineKeyboardMarkup([[InlineKeyboardButton("Tap me", callback_data="tapped")]])
    await update.message.reply_text("Hello from Moonlygram!", reply_markup=keyboard)


async def on_tap(update, context):
    await update.callback_query.answer("You tapped it!")


app = Application.builder().token("YOUR_BOT_TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.add_handler(CallbackQueryHandler(on_tap, pattern="^tapped$"))
app.run_polling()

Features

• Familiar: a python-telegram-bot-style API: Application, handlers, filters, and (update, context) callbacks. Existing bots port with little more than renamed imports.
• Async: receiving and dispatch run concurrently, so a slow handler never stalls the next update.
• Performant: a non-blocking poll loop, optional parallel dispatch, a built-in rate limiter, and a dependency-free JobQueue.
• Rich: send rich messages (headings, tables, collapsibles, math) with a composable, auto-escaping builder, convert Markdown in one call, or build them from Bot API 10.3 structured blocks. No other library has this.
• Type-hinted: ships py.typed and passes mypy --strict. The received types are generated from the Bot API schema, so they cannot silently drift.
• Lightweight: one dependency (httpx). Pure HTTP, with no MTProto, no api_id/api_hash, and no C extensions.
• Batteries included: conversations, persistence, scheduled jobs, arbitrary callback data, and both polling and webhooks.

Resources

• Documentation: https://atarixiafamine.github.io/Moonlygram/
• Migrating from python-telegram-bot: https://atarixiafamine.github.io/Moonlygram/migrating/
• Examples: examples/
• Changelog: CHANGELOG.md

Roadmap

Core messaging, media, chat and member administration, bot configuration, forum topics, stickers, inline mode, and payments / Telegram Stars are all covered, and every modelled method accepts every parameter the Bot API defines for it (a drift test enforces this against the vendored spec). Still in progress: the niche Bot API domains of business accounts, games, gifts and stories, checklists, and passport / paid media.

Contributing

Contributions are welcome. See CONTRIBUTING.md; it covers the spec-driven codegen workflow for data types (edit the spec or overrides, regenerate, then test).

License

Released under the MIT License. See LICENSE. Copyright © 2026 AtarixiaFamine.