sayagram 0.4.0

Modern async Telegram framework for bots, user clients, and MTProto apps.

Sayagram

High-performance async Telegram framework for Python bots, userbots, and hybrid applications.

Sayagram gives you one framework API, one package name, and one install command. It includes a native Sayagram Bot API engine for dependency-free bot work, plus lazy advanced engines for larger Telegram applications.

Telegram custom emoji support is implemented with official message entities. Sayagram can send custom emoji where Telegram allows it, but it cannot unlock Telegram Premium or bypass Telegram platform limits.

Installation

pip install -U sayagram

Quick Start

from sayagram import Client, filters

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


@app.on_message(filters.command("start") & filters.private)
async def start(client, message):
    await message.reply_text("Hello 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())

Custom Emoji

Telegram custom emoji entities must wrap a normal fallback emoji. Sayagram calculates the correct UTF-16 offsets for Bot API and MTProto libraries.

from sayagram import Client, custom_emoji, render

app = Client("emoji-bot", bot_token="123456:BOT_TOKEN")


async def send_approved(chat_id: int) -> None:
    text, entities = render(
        [
            "Approved ",
            custom_emoji("5368324170671202286", "\U0001F44D"),
        ]
    )
    await app.send_message(chat_id, text, entities=entities)

Compact markup is supported too:

await app.send_custom_emoji_message(
    123456789,
    "Approved {emoji:5368324170671202286|\U0001F44D}",
)

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.

Backend Access

Sayagram gives you a common framework API for common work:

• start() and stop()
• run() and run_forever()
• on_message() with sayagram.filters
• send_message()
• send_custom_emoji_message()
• edit_message()
• delete_message()
• download_media()

For advanced Telegram features, use app.raw and call the selected backend directly.

Publishing

Build locally:

python -m build

Upload manually when you have a PyPI token:

python -m twine upload dist/*

The repository also includes a GitHub Actions workflow for PyPI Trusted Publishing. Configure a PyPI trusted publisher for shnwazdeveloper/sayagram, then create a GitHub release to publish.