sayagram 0.4.3

High-performance Telegram API framework for Python.

Sayagram

High-Performance Telegram API Framework for Python

Sayagram is an elegant, asynchronous, and deeply customizable Python framework for Telegram bots, user clients, and MTProto-powered applications. It gives developers a clean Sayagram API for building scalable Telegram projects with minimal boilerplate.

Why Sayagram?

When building production-grade Telegram applications, you need a framework that stays simple at the surface and powerful underneath.

• Modern Telegram UX: Custom emoji entities, inline keyboard helpers, callback data, and clean message reply tools.
• High-concurrency ready: Built around Python asyncio for responsive bot and user automation workflows.
• Unified app style: Write intuitive Client, filters, and Message code for standard bots and larger Telegram applications.
• Direct escape hatch: Use app.raw when you need precise low-level control.
• One install command: Publish, install, and import as Sayagram.

Installation

Install Sayagram from PyPI:

pip install -U sayagram

Requires Python 3.10 or higher.

Quick Start

The Standard Bot

Build a responsive Telegram bot with a small, readable Sayagram app.

from sayagram import Client, filters

app = Client(
    "my_bot",
    bot_token="your_bot_token",
)


@app.on_message(filters.command("start") & filters.private)
async def hello(client, message):
    await message.reply_text("Hello from Sayagram!")


if __name__ == "__main__":
    app.run()

Smart Keyboards and Custom Emojis

Sayagram includes small UI helpers and custom emoji entity builders for richer Telegram messages.

from sayagram import (
    Client,
    InlineKeyboardButton,
    InlineKeyboardMarkup,
    custom_emoji,
    filters,
    render,
)

app = Client("menu_bot", bot_token="your_bot_token")


@app.on_message(filters.command("menu"))
async def send_menu(client, message):
    keyboard = InlineKeyboardMarkup(
        [
            [
                InlineKeyboardButton(
                    "Confirm Action",
                    callback_data="confirm",
                )
            ]
        ]
    )

    text, entities = render(
        [
            "Please confirm your action ",
            custom_emoji("5368324170671202286", "\U0001F44D"),
        ]
    )

    await message.reply_text(text, entities=entities, reply_markup=keyboard)

Direct Async Usage

import asyncio

from sayagram import Sayagram


async def main() -> None:
    async with Sayagram(api_id=12345, api_hash="api_hash") as app:
        await app.send_message("me", "Hello from Sayagram")


asyncio.run(main())

Common Framework API

Sayagram gives you a common framework API for everyday Telegram work:

• Client(...): create one Sayagram app for bots or advanced clients.
• filters.command(...), filters.private, filters.group: route updates with readable async filters.
• Message.reply_text(...): reply from a normalized message object.
• send_message(...): send text with entities, keyboards, and extra options.
• send_custom_emoji_message(...): send custom emoji entity markup safely.
• edit_message(...): edit text without changing app style.
• delete_message(...): remove messages with one call.
• download_media(...): download files through the selected engine.
• InlineKeyboardMarkup and InlineKeyboardButton: build inline keyboards directly from Sayagram.
• app.raw: access the selected low-level engine when you need advanced Telegram control.

Environment Configuration

Sayagram.from_env() reads these variables:

• SAYAGRAM_BACKEND: auto, bot, user, or mtproto.
• SAYAGRAM_BOT_TOKEN or BOT_TOKEN.
• SAYAGRAM_API_ID or API_ID.
• SAYAGRAM_API_HASH or API_HASH.
• SAYAGRAM_SESSION.

When backend="auto", Sayagram chooses the right engine from your credentials.

Contributing and Support

Sayagram is actively developed and welcomes feedback, bug reports, and feature ideas.

• Issue tracker: GitHub Issues
• Source code: GitHub Repository
• Package: PyPI Project