toptl-aiogram

aiogram plugin for TOP.TL — auto-post bot stats and check votes.

Installation

pip install toptl-aiogram

Quick Start

from aiogram import Bot, Dispatcher
from toptl import AsyncTopTL
from toptl_aiogram import TopTLMiddleware

bot = Bot(token="BOT_TOKEN")
dp = Dispatcher()

toptl = AsyncTopTL("your-toptl-api-token")
mw = TopTLMiddleware(toptl, "mybot")

# Register middleware — stats are posted automatically
dp.message.middleware(mw)

The middleware tracks unique users, groups, and channels your bot sees and auto-posts stats to TOP.TL every 30 minutes (only when counts change).

Vote-Gating

Restrict commands to users who have voted for your bot:

from toptl_aiogram import TopTLMiddleware, vote_required

mw = TopTLMiddleware(toptl, "mybot")
dp.message.middleware(mw)

# Gate a specific router
premium_router = Router()
premium_router.message.middleware(vote_required(mw, "Vote at https://top.tl/mybot to unlock this!"))

@premium_router.message(Command("premium"))
async def premium_cmd(message: Message):
    await message.answer("Thanks for voting! Here's your premium content.")

Check Votes Manually

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

The toptl key is automatically injected into handler data by the middleware.

Options

Parameter	Type	Default	Description
client	AsyncTopTL	required	TOP.TL API client from the toptl package
username	str	required	Your bot's username on TOP.TL
autopost	bool	True	Auto-post stats on a timer
interval	int	1800	Seconds between stat posts (server may override)
only_on_change	bool	True	Skip posting if counts haven't changed

Cleanup

Stop the autopost loop when shutting down:

@dp.shutdown()
async def on_shutdown():
    mw.stop()
    await toptl.close()

Links

• TOP.TL
• toptl Python SDK
• API Docs