toptl-ptb

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

Install

pip install toptl-ptb

Python 3.9+. Pulls in toptl>=0.1.1 and python-telegram-bot>=21.0.

Quick start

from telegram.ext import ApplicationBuilder, CommandHandler
from toptl import AsyncTopTL
from toptl_ptb import setup_toptl, vote_required

app = ApplicationBuilder().token("BOT_TOKEN").build()
client = AsyncTopTL("toptl_xxx")

# One line installs the tracker + autoposter on the Application.
plugin = setup_toptl(app, client, "mybot")

@vote_required(plugin, vote_url="https://top.tl/mybot")
async def premium(update, context):
    await update.message.reply_text("Thanks for voting!")

app.add_handler(CommandHandler("premium", premium))
app.run_polling()

setup_toptl does three things:

1. Adds a low-priority TypeHandler that records unique user / group / channel IDs from every update.
2. Schedules a JobQueue task that flushes those counts to TOP.TL every 30 min — only when they changed, so you're not burning API quota on idle minutes.
3. Returns a TopTLPlugin handle you use for vote checks and manual flushes.

Vote gating

The @vote_required(plugin) decorator short-circuits the handler and replies with a prompt when the user hasn't voted:

@vote_required(plugin, message="Vote to unlock this: https://top.tl/mybot")
async def premium(update, context):
    ...

For checks inside existing logic:

if await plugin.has_voted(update.effective_user.id):
    ...

Both paths fail-open — network errors never block your handler, they just count as "not voted" and log at ERROR level.

Tuning the autoposter

plugin = setup_toptl(
    app, client, "mybot",
    interval_seconds=15 * 60,   # flush every 15 min instead of 30
    first_seconds=5,            # first flush 5s after startup
    handler_group=-1,           # override the default -100 group
)

To flush manually — for example from a graceful-shutdown hook:

async def post_shutdown(application):
    await plugin.post_now()
    await client.aclose()

app.post_shutdown = post_shutdown

Requirements

• python-telegram-bot[job-queue]>=21.0 — the [job-queue] extra enables the autoposter. Without it you can still call plugin.post_now() from your own schedule (e.g. an existing apscheduler).
• Python 3.9 or newer.

License

MIT.

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