sayagram 0.4.4

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

Install every supported engine in one command:

pip install -U "sayagram[all]"

Or install only the engine you want:

pip install -U "sayagram[aiogram]"
pip install -U "sayagram[telethon]"
pip install -U "sayagram[pyrogram]"
pip install -U "sayagram[srigram]"
pip install -U "sayagram[speedup]"

Requires Python 3.10 or higher.

Engine Support

Sayagram supports a native dependency-free Bot API engine and optional adapters for aiogram, Telethon, Pyrogram, and Srigram. You keep the same Sayagram API and choose the engine with backend=....

Backend	Powered by	Best for	Install
sayagram / native	Sayagram Bot API	Lean bot projects	pip install -U sayagram
aiogram	aiogram 3.x	Bot API projects that already use aiogram	pip install -U "sayagram[aiogram]"
telethon	Telethon 1.x	MTProto users, userbots, advanced clients	pip install -U "sayagram[telethon]"
pyrogram	Pyrogram 2.x	Pyrogram-style MTProto apps	pip install -U "sayagram[pyrogram]"
srigram	Srigram 2.x	Srigram/Pyrogram-compatible MTProto apps	pip install -U "sayagram[srigram]"

Use supported_backends() and backend_status() when you want to inspect what is available in the current Python environment.

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)

Same API, Different Engines

from sayagram import Client, filters

app = Client(
    "my_app",
    backend="pyrogram",  # sayagram, aiogram, telethon, pyrogram, or srigram
    api_id=123456,
    api_hash="your_api_hash",
)


@app.on_message(filters.command("ping"))
async def ping(client, message):
    await message.reply_text("pong from Sayagram")


app.run()

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.
• get_me(...): verify the current bot or MTProto account.
• 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 or SAYAGRAM_ENGINE: auto, sayagram, aiogram, telethon, pyrogram, srigram, 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.

Local Credential Test

Use the local examples to check real Telegram credentials without saving secrets in files.

$env:SAYAGRAM_BOT_TOKEN="your_bot_token"
$env:SAYAGRAM_API_ID="your_api_id"
$env:SAYAGRAM_API_HASH="your_api_hash"
$env:PYTHONPATH="src"

python examples/check_credentials.py
python examples/local_bot.py

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