toptl-aiogram 0.1.0

aiogram plugin for TOP.TL — autopost bot stats, gate handlers behind votes, handle vote webhooks.

toptl-aiogram

Official TOP.TL plugin for aiogram 3. One call wires up autoposted bot stats, vote-gated handlers, and webhook helpers — all on top of the toptl SDK.

Install

pip install toptl-aiogram

Python 3.9+. Pulls in toptl>=0.1.1 and aiogram>=3.0.

Quick start

import asyncio
from aiogram import Bot, Dispatcher
from aiogram.filters import Command
from aiogram.types import Message
from toptl import AsyncTopTL
from toptl_aiogram import setup_toptl, vote_required

async def main():
    bot = Bot("BOT_TOKEN")
    dp = Dispatcher()
    client = AsyncTopTL("toptl_xxx")

    # One call installs the middleware + autoposter, tied to dp's
    # startup/shutdown hooks — no background task bookkeeping for you.
    plugin = setup_toptl(dp, client, "mybot")

    @dp.message(Command("premium"))
    @vote_required(plugin, vote_url="https://top.tl/mybot")
    async def premium(message: Message):
        await message.answer("Thanks for voting!")

    await dp.start_polling(bot)

asyncio.run(main())

setup_toptl does three things:

1. Registers a middleware on dp.update.middleware that records unique user / group / channel IDs from every update (messages, callbacks, chat_member, …).
2. Hooks an AsyncAutoposter into the dispatcher's startup/shutdown events — it flushes stats every 30 min, only when counts changed.
3. Returns a TopTLPlugin handle you use for vote checks and manual flushes.

Vote gating

@dp.message(Command("premium"))
@vote_required(plugin, message="Vote first: https://top.tl/mybot")
async def premium(message: Message):
    ...

Works on message and callback-query handlers. Network or auth failures fall through as "not voted" and log at ERROR level — vote gates never brick your bot.

For checks inside existing logic:

@dp.message(Command("check"))
async def check(message: Message):
    if await plugin.has_voted(message.from_user.id):
        await message.answer("You voted, thanks!")
    else:
        await message.answer("Please vote at https://top.tl/mybot")

The plugin handle is also injected into handler data under data["toptl"]:

async def handler(message: Message, toptl):  # aiogram reads the param name
    if await toptl.has_voted(message.from_user.id):
        ...

Tuning the autoposter

plugin = setup_toptl(
    dp, client, "mybot",
    interval_seconds=15 * 60,  # flush every 15 min instead of 30
)

Manual flush (e.g. before shutdown):

await plugin.post_now()

Requirements

• aiogram>=3.0
• Python 3.9+

License

MIT.

---

Part of the TOP.TL developer ecosystem. Issues and contributions: top-tl/aiogram.