Skip to main content

nextgram

Telegram Bot API 10.3 rich messages — tables, details, lists, colored buttons, drafts and ephemeral messages, with an automatic plain-text fallback when a rich message is rejected — plus Bot API 10.4 HTML widgets (sendWidget and friends, see Widgets below), for six frameworks:

Framework Module Rich messages Widgets
Pyrogram / Pyrofork / Kurigram nextgram.rich_ui (also the top-level nextgram.* names) native (InputRichMessage) when the installed build supports it, HTML fallback otherwise yes
Telethon nextgram.telethon native MTProto rich_message when the installed build supports it, HTML fallback otherwise yes
aiogram nextgram.aiogram_rich sendRichMessage over the plain Bot HTTP API, HTML fallback otherwise yes
python-telegram-bot nextgram.ptb_rich sendRichMessage over the plain Bot HTTP API, HTML fallback otherwise yes

Pyrogram, Pyrofork and Kurigram are one family — three distributions of the exact same pyrogram package name — so one implementation already covers all three; there is nothing framework-specific left to add for them. nextgram.widgets is framework-agnostic by construction (it only ever needs a bot token) and already works unmodified from every framework above.

Installing nextgram on its own needs none of Pyrogram, Pyrofork, Kurigram, Telethon, aiogram or python-telegram-bot — only httpx, for the HTTP calls nextgram.widgets (and the aiogram/python-telegram-bot rich senders) make. Each framework's own module is only imported when you import it, so a bot using just one framework never needs the others installed.

Install

pip install nextgram

With the framework you actually use:

pip install "nextgram[pyrogram]"      # Pyrogram, Pyrofork or Kurigram (one package: kurigram)
pip install "nextgram[telethon]"
pip install "nextgram[aiogram]"
pip install "nextgram[ptb]"           # python-telegram-bot
pip install "nextgram[all]"           # every framework, for trying things out

Or straight from GitHub:

pip install git+https://github.com/Badmunda05/nextgram.git

How to import

Import only what you need (recommended):

from nextgram import rich_send, rich_reply, rich_edit
from nextgram import rich_heading, rich_note, rich_table, rich_kv_table
from nextgram import rich_button, rich_button_row

Or import the whole package and use the nextgram. prefix:

import nextgram

text = nextgram.rich_heading("Hello", level=3)
await nextgram.rich_send(client, chat_id, text)

Or import from the submodule directly:

from nextgram.rich_ui import rich_send, rich_button

Check the version and whether your build supports rich messages:

import nextgram

print(nextgram.__version__)
print(nextgram.RICH_AVAILABLE)

Quick example

from nextgram import rich_send, rich_heading, rich_kv_table, rich_esc

text = (
    rich_heading("Now Playing", level=3)
    + rich_kv_table([
        ("Title", rich_esc("Song name")),
        ("Duration", "3:27"),
    ])
)

await rich_send(client, chat_id, text)

Buttons

Buttons are part of the message HTML, so append them to the content (there is no reply_markup):

from nextgram import rich_button, rich_button_row, rich_send

buttons = (
    rich_button_row(
        rich_button("Support", url="https://t.me/BadmundaXd", style="primary"),
        rich_button("Pause", callback_data="pause", style="success"),
    )
    + rich_button_row(rich_button("Close", callback_data="close", style="danger"))
)

await rich_send(client, chat_id, text + buttons)
  • style: primary (blue), success (green), danger (red), link, or leave it out for grey.
  • URL button: type="url" with url="...".
  • Callback button: type="callback_data" with data="...".
  • Copy button: type="copy_text" with text="..." — one tap copies the value to the clipboard. The text must be 1–256 characters, and a copy button takes no url or callback_data:
rich_button("Copy ID", copy_text="5368324170671202286", style="primary")

When a message falls back to plain text, a copy button becomes its bold label — the value itself is not shown.

  • rich_button_row(..., align="center") aligns the row (left, center, right).

Random colours like an inline keyboard:

import random

style = random.choice(["primary", "success", "danger"])
rich_button("Shuffle", callback_data="shuffle", style=style)

Page indexation

The bottom line of a paginated message is an italic footer:

from nextgram import rich_page_index

rich_page_index(2, 5, total=42)              # Page 2 of 5 • total 42
rich_page_index(2, 5)                        # Page 2 of 5
rich_page_index(2, 5, label="Settings")     # Settings • Page 2 of 5

Page counts are 1-based, pages must cover page, and total must not be negative. In plain-text fallback the line survives as Page 2 of 5 • total 42.

Premium (custom) emoji

from nextgram import rich_emoji, rich_send

await rich_send(client, chat_id, "Nice " + rich_emoji("5368324170671202286", "🔥") + " work!")

rich_emoji(document_id, alt) emits the Bot API form <tg-emoji emoji-id="...">🔥</tg-emoji>. The id is the custom-emoji sticker's document id — not a file_id, pack name, or t.me/addemoji link, and it cannot be guessed. Get one from a message that already contains the emoji (its custom_emoji entity), from a sticker set (Sticker.custom_emoji_id), or verify one you have with:

from nextgram import fetch_custom_emoji

sticker = await fetch_custom_emoji(client, "5368324170671202286")
print(sticker.emoji)  # the fallback glyph to use as alt

alt is the plain emoji shown where the custom emoji cannot be displayed (notifications, forwards by non-premium users, and nextgram's plain-text fallback), so it is required. A bot may send custom emoji if its owner has Telegram Premium (direct messages to private, group and supergroup chats) or if the bot purchased additional usernames on Fragment (also channels). If the bot is not eligible, Telegram rejects the message and nextgram falls back to the alt text.

Register emoji once and use them by name, including :shortcode: expansion in any text:

from nextgram import (
    add_html_hook, expand_emoji_shortcodes,
    register_custom_emoji, rich_emoji_named,
)

register_custom_emoji("fire", "5368324170671202286", "🔥")
add_html_hook(expand_emoji_shortcodes)

await rich_send(client, chat_id, "Nice :fire: work!")  # :fire: expands on send
rich_emoji_named("fire")  # the same markup, directly

Only registered names expand; unknown shortcodes and times like 12:30 are left alone, and shortcodes inside <pre>/<code> are never expanded. register_custom_emojis({...}) registers many at once, custom_emoji_names() lists them, clear_custom_emojis() clears them.

MarkdownV2 form, and the typed block form for rich_send_blocks:

from nextgram import rich_emoji_markdown, rich_text_custom_emoji

rich_emoji_markdown("5368324170671202286", "🔥")  # ![🔥](tg://emoji?id=...)
rich_text_custom_emoji("5368324170671202286", "🔥")  # RichTextCustomEmoji

The older Pyrogram form <emoji id="...">🔥</emoji> still works anywhere in nextgram input: it is normalised to <tg-emoji emoji-id="..."> before sending, since the rich path sends HTML raw to Telegram.

Multiple collapsibles

One section is rich_details(summary, body, open=False). For several sections in one message, build them as a group:

from nextgram import rich_details_group

text = rich_details_group([
    ("Install", "pip install nextgram"),
    ("Usage", "See the examples below.", True),  # open by default
    {"summary": "Source", "body": "Clone the repo and read rich_ui.py"},
])

open_first=True opens only the first section, open_all=True opens every section, and a per-section open wins over both. Sections open and close independently: Telegram has no accordion mode.

Sections nest, too — pass a rich_details(...) as a body, or build a tree with rich_details_nested:

from nextgram import rich_details_nested

text = rich_details_nested("Guide", "Start here.", children=[
    ("Install", "pip install nextgram"),
    {"summary": "Advanced", "body": "", "children": [
        ("Source", "Clone the repo and read rich_ui.py"),
    ]},
])

Telegram allows up to 16 levels of nested formatting and blocks (and up to 500 blocks in a message, nested details included), so nesting deeper than 16 raises ValueError instead of failing at send time.

Typed blocks for rich_send_blocks (nest one details block inside another the same way):

from nextgram import rich_block_details, rich_block_paragraph

block = rich_block_details("Guide", [
    rich_block_paragraph("Start here."),
    rich_block_details("Advanced", [rich_block_paragraph("Deep dive.")]),
], open=True)

When a rich message is rejected and nextgram falls back to plain text, collapsibles become an indented outline (▸ per section, deeper sections indented), so the structure survives instead of collapsing flat.

Todo lists

A checklist renders as native checkboxes — not emoji bullets:

from nextgram import rich_todo_list

text = rich_todo_list([
    ("Buy milk", False),
    ("Book tickets", True),
    "Call mom",  # a plain string is an unchecked item
    {"text": "Ship it", "done": True},
])

That is Rich HTML (<li><input type="checkbox" checked>...). The same list as Rich Markdown, for rich_send(..., markdown=True):

from nextgram import rich_todo_list_markdown

rich_todo_list_markdown([("Buy milk", False), ("Book tickets", True)])
# "- [ ] Buy milk\n- [x] Book tickets"

Or as typed blocks, for rich_send_blocks (Kurigram) and telethon_rich_send_blocks (Telethon) — both carry the checkbox as a real field (has_checkbox / is_checked, checkbox / checked):

from nextgram import rich_block_todo_list
from nextgram.telethon import telethon_block_todo_list

rich_block_todo_list([("Buy milk", False), ("Book tickets", True)])
telethon_block_todo_list([("Buy milk", False), ("Book tickets", True)])

The boxes show the state you send; they are not tappable toggles. To flip an item, re-send or edit the message with the new state. When a message falls back to plain text, todo items render as [ ] Buy milk / [x] Book tickets, so the state survives there too.

Content blocks

from nextgram import (
    rich_heading, rich_note, rich_code, rich_pre, rich_list, rich_hr,
    rich_footer, rich_pull_quote, rich_math, rich_anchor, rich_thinking,
    rich_table, rich_kv_table, rich_details, rich_img, rich_esc,
)

rich_list(["one", "two"])
rich_list(["first", "second"], ordered=True)
rich_pre("print('hi')", language="python")
rich_table(["A"], [None, "single"])  # None rows render empty, string rows single-cell
rich_math("x^2 + y^2 = z^2")
rich_details("More", "hidden text", open=True)

Code, inside and out

rich_pre escapes everything, so a code block is always literal text. To nest inline formatting inside a code block — bold a keyword, mark a value as inline code — use rich_pre_rich, whose body is HTML used as-is (escape user text with rich_esc first):

from nextgram import rich_pre_rich

rich_pre_rich("<b>pip</b> install <code>nextgram</code>", language="bash")

The language travels in the <code class="language-..."> wrapper — the form Telegram's parser reads. Any language string passes through; the client highlights the languages it knows. A fenced Markdown block is literal, so this nesting exists only in the HTML and typed-block forms.

As typed blocks, for rich_send_blocks (Kurigram) and telethon_rich_send_blocks (Telethon), with the same segment model — plain strings or (kind, text) pairs with kind plain/bold/italic/ code, or RichText objects from rich_text_bold / rich_text_italic / rich_text_code:

from nextgram import rich_block_preformatted
from nextgram.telethon import telethon_block_preformatted

rich_block_preformatted([
    ("bold", "pip"), " install ", ("code", "nextgram"),
], language="bash")
telethon_block_preformatted([
    ("bold", "pip"), " install ", ("code", "nextgram"),
], language="bash")

A pre-only message goes out over plain HTML (classic HTML already renders <pre>), and joins the rich path when combined with rich-only content such as a heading or a table.

Map, collage, slideshow, audio, video

These blocks are sent as typed Kurigram blocks with rich_send_blocks:

from pyrogram.types import InputRichBlockMap
from nextgram import rich_send_blocks

await rich_send_blocks(client, chat_id, [InputRichBlockMap(...)])

Sending and editing

from nextgram import rich_reply, rich_edit, rich_edit_inline, rich_answer

msg = await rich_reply(message, text)
await rich_edit(msg, text + buttons)
await rich_edit(callback_query, text + buttons)
await rich_edit_inline(client, inline_message_id, text)
await rich_answer(callback_query, text)

Extra options on rich_send, rich_reply and rich_edit:

await rich_send(
    client, chat_id, text,
    business_connection_id="...",
    direct_messages_topic_id=5,
    message_thread_id=9,
    allow_paid_broadcast=True,
    suggested_post_parameters=params,
    disable_notification=True,
    protect_content=True,
    effect_id=123,
    is_rtl=True,
    skip_entity_detection=True,
)

Markdown instead of HTML:

await rich_send(client, chat_id, "# Title\n\n**bold** text", markdown=True)

Telethon (MTProto)

Telethon has no send_rich_message, but the same rich payload travels over MTProto as a native request. nextgram.telethon builds it for you — the HTML builders are transport-independent, so the same text works on both transports:

from telethon import TelegramClient
from nextgram import rich_heading, rich_details_group
from nextgram.telethon import telethon_rich_send, telethon_rich_edit

client = TelegramClient("session", api_id, api_hash)

text = rich_heading("Now Playing", level=3) + rich_details_group([
    ("Track", "Song name"),
    ("Lyrics", "La la la"),
])

msg = await telethon_rich_send(client, chat_id, text)
await telethon_rich_edit(msg, text + " (updated)")

How it works: the adapter sends a raw messages.SendMessageRequest / messages.EditMessageRequest with rich_message set to an InputRichMessageHTML / InputRichMessageMarkdown. The TL schema still requires the ordinary message field, so it is filled with the same rich source text. Telethon resolves the peer and generates random_id itself when the request is invoked.

Like rich_send, a rich request Telegram rejects falls back to an ordinary Telethon send_message with the plain fallback text — and Telethon's HTML parser understands <tg-emoji>, so premium emoji survive the plain path too. A raw send returns Updates, so the adapter resolves the real Message from it before returning — msg.id works on the return value of every send/edit call. A FloodWaitError is re-raised from both paths, never swallowed into None and never fallen back from, so the caller can sleep and retry. The builders for replies and blocks mirror the Pyrogram side:

from nextgram.telethon import (
    telethon_rich_reply, telethon_rich_send_blocks,
    telethon_block_details, telethon_block_paragraph,
)

await telethon_rich_reply(message, text)
await telethon_rich_send_blocks(client, chat_id, [
    telethon_block_details("Guide", [telethon_block_paragraph("Start here.")]),
])

Blocks are Telethon PageBlock objects, not Pyrogram InputRichBlock objects: PageBlockDetails(blocks, title, open) takes its arguments in the opposite order to Pyrogram's InputRichBlockDetails(summary, blocks). telethon_send_request / telethon_edit_request return the raw requests directly if you want to invoke them yourself, and TELETHON_RICH_AVAILABLE reports whether the installed Telethon build has the rich-message types (telethon>=1.45 is known to work).

aiogram

aiogram has no MTProto layer and no native rich-message method, so nextgram.aiogram_rich goes straight to the plain Bot HTTP API's sendRichMessage endpoint — the same endpoint the Pyrogram side falls back to over HTTP for typed blocks — and falls back further to an ordinary sendMessage with the plain-fallback text if that is rejected:

from aiogram import Bot, Dispatcher
from aiogram.filters import Command
from nextgram import rich_heading, rich_details_group
from nextgram.aiogram_rich import aiogram_rich_send, aiogram_rich_reply

bot = Bot(token=TOKEN)
dp = Dispatcher()

text = rich_heading("Now Playing", level=3) + rich_details_group([
    ("Track", "Song name"),
    ("Lyrics", "La la la"),
])

@dp.message(Command("np"))
async def now_playing(message):
    await aiogram_rich_reply(message, text)

aiogram_rich_send(bot, chat_id, html_text, ...) takes a Bot instance directly, reading its token from bot.token. aiogram_rich_reply(message, html_text, ...) reads both the bot and the chat off an aiogram Message automatically (aiogram sets message.bot on every incoming message). aiogram_rich_edit(message, html_text, ...) edits in place; pass chat_id=/message_id= instead of message to edit one you don't have the Message object for. A reply_markup can be an aiogram InlineKeyboardMarkup or a plain dict — it's converted automatically.

These functions return the Bot API result dict (with message_id), not an aiogram Message object — aiogram's own send methods are never called, since the whole point is reaching sendRichMessage, which aiogram doesn't know about.

python-telegram-bot

Same situation as aiogram: no MTProto, no native rich-message method, so nextgram.ptb_rich also goes through the plain Bot HTTP API's sendRichMessage, with the same fallback to sendMessage:

from telegram.ext import Application, CommandHandler
from nextgram import rich_heading, rich_details_group
from nextgram.ptb_rich import ptb_rich_reply

text = rich_heading("Now Playing", level=3) + rich_details_group([
    ("Track", "Song name"),
    ("Lyrics", "La la la"),
])

async def now_playing(update, context):
    await ptb_rich_reply(update, text)

app = Application.builder().token(TOKEN).build()
app.add_handler(CommandHandler("np", now_playing))

ptb_rich_send(bot, chat_id, html_text, ...) takes a Bot (or context.bot) directly, reading its token from bot.token. ptb_rich_reply(message_or_update, html_text, ...) accepts either a telegram.Message or a telegram.Update (its .effective_message is used), and reads the bot via message.get_bot(). ptb_rich_edit(message, html_text, ...) edits in place; pass chat_id=/message_id=/bot= instead of message to edit one you don't have the Message object for. A reply_markup can be a python-telegram-bot InlineKeyboardMarkup or a plain dict.

Like aiogram, these functions return the Bot API result dict, not a telegram.Message.

How the HTTP-based sendRichMessage path works, and what's unconfirmed

nextgram.http_rich is what aiogram_rich and ptb_rich both build on. It POSTs to https://api.telegram.org/bot<token>/sendRichMessage with {"chat_id": ..., "rich_message": {"html": ...}} — this is a real, already-used endpoint (rich_ui._send_blocks_via_http calls the same one for typed blocks), not a guess specific to this module. Sending is reasonably solid: a rejection is caught and the message goes out as plain HTML instead.

Editing is the part that's genuinely unconfirmed: there is no documented standalone HTTP method for editing a rich message, only Pyrogram's native, MTProto-level edit_message_text(..., rich_message=...). edit_rich_html_via_http tries the same rich_message field on the plain HTTP editMessageText call first — it may or may not be honoured by the server — and falls back to a plain-HTML edit either way, so an edit never fails outright; it may just silently land as a plain-text edit instead of a rich one. If you hit this, the plain-text edit is still correct content, just not rich.

Ephemeral messages

from nextgram import rich_reply, ephemeral_edit, ephemeral_delete

sent = await rich_reply(message, text, ephemeral=True)
await ephemeral_edit(sent, new_text)
await ephemeral_delete(sent)

Streaming drafts

from nextgram import RichDraft, rich_heading

async with RichDraft(client, chat_id, can_stop=True) as draft:
    await draft.update(rich_heading("Searching..."))
    await draft.finish(final_text)

Fallback and debugging

If Telegram rejects a rich message, nextgram sends a readable plain-text version instead (buttons become links or bold text). To see why a rich message failed:

import logging

logging.getLogger("nextgram").setLevel(logging.DEBUG)

Transform HTML before it is sent (for example expanding emoji shortcodes):

from nextgram import add_html_hook, expand_emoji_shortcodes, register_custom_emoji

register_custom_emoji("fire", "5368324170671202286", "🔥")
add_html_hook(expand_emoji_shortcodes)  # turns :fire: into a premium emoji

Plain-text helpers: rich_to_plain(html) and rich_caption(html).

Everything you can import

RICH_AVAILABLE, rich_esc, sanitize_display_name, rich_heading, rich_note, rich_table, rich_kv_table, rich_details, rich_details_group, rich_details_nested, rich_block_details, rich_block_paragraph, rich_code, rich_pre, rich_pre_rich, rich_block_preformatted, rich_text_bold, rich_text_italic, rich_text_code, rich_list, rich_todo_list, rich_todo_list_markdown, rich_block_todo_list, rich_hr, rich_footer, rich_page_index, rich_pull_quote, rich_math, rich_anchor, rich_thinking, rich_img, rich_emoji, rich_emoji_markdown, rich_text_custom_emoji, register_custom_emoji, register_custom_emojis, clear_custom_emojis, custom_emoji_names, rich_emoji_named, expand_emoji_shortcodes, fetch_custom_emoji, rich_button, rich_button_row, rich_to_plain, rich_caption, add_html_hook, clear_html_hooks, rich_send, rich_send_blocks, rich_reply, rich_edit, rich_edit_inline, rich_answer, ephemeral_edit, ephemeral_delete, RichDraft

Telethon transport (from nextgram.telethon import ...): TELETHON_RICH_AVAILABLE, telethon_input_rich, telethon_send_request, telethon_edit_request, telethon_block_paragraph, telethon_block_details, telethon_block_todo_list, telethon_block_preformatted, telethon_rich_send, telethon_rich_send_blocks, telethon_rich_reply, telethon_rich_edit

aiogram transport (from nextgram.aiogram_rich import ...): aiogram_bot_token, aiogram_rich_send, aiogram_rich_reply, aiogram_rich_edit

python-telegram-bot transport (from nextgram.ptb_rich import ...): ptb_bot_token, ptb_rich_send, ptb_rich_reply, ptb_rich_edit

Shared HTTP layer behind both of the above (from nextgram.http_rich import ...): send_rich_html_via_http, edit_rich_html_via_http, coerce_markup_to_dict

Widgets (from nextgram import ..., or from nextgram.widgets import ...) — the same names work from every framework above, including Telethon, aiogram and python-telegram-bot, since this module never touches a framework's client type directly, only a bot token: WIDGET_NATIVE_AVAILABLE, MAX_WIDGET_HTML_COMPRESSED_BYTES, MAX_WIDGET_QUERY_REQUEST_BYTES, MAX_WIDGET_ANSWER_DATA_BYTES, MIN_WIDGET_CACHE_TIME, MAX_WIDGET_CACHE_TIME, MAX_WALLET_MESSAGES, WidgetAPIError, WalletCard, WalletSentTransaction, WalletSignDataResult, WidgetQuery, SharedWidgetQuery, widget_html_compressed_size, validate_widget_html, validate_nanoton_amount, parse_widget_query, parse_shared_widget_query, extract_widget_query, build_wallet_transaction_answer, send_widget, send_shared_widget, edit_message_widget_data, edit_shared_widget_data, answer_widget_query, input_widget_message_content, input_shared_widget_message_content

Widgets (Bot API 10.4)

nextgram.widgets adds Telegram's widgets: small, sandboxed HTML blocks a bot draws inside a message (core.telegram.org/bots/widgets). This is a separate feature from the rich messages above — it does not need RICH_AVAILABLE/Kurigram's rich-message support, and nothing in this section changes how rich_send and friends behave.

from nextgram import send_widget, answer_widget_query, parse_widget_query

msg = await send_widget(
    client, chat_id,
    "<!doctype html><html><body>Hello from a widget</body></html>",
    allow_queries=True,
)

Every function in this module talks to the plain Bot HTTP API directly (https://api.telegram.org/bot<token>/...), the same escape hatch rich_send_blocks already uses for typed blocks — it does not depend on any framework's client having native MTProto/HTTP support for widgets (no known release of any of the six frameworks does yet). Pass token=... explicitly, or pass a client that already exposes the token itself: .bot_token (Pyrogram, Pyrofork, Kurigram) or .token (aiogram, python-telegram-bot) are both read automatically. Telethon's TelegramClient doesn't keep the bot token it logged in with, so pass token=... for it. If a future release of any framework adds native widget support, this module prefers it automatically (WIDGET_NATIVE_AVAILABLE) and only falls back to the raw HTTP call on failure or absence.

from nextgram import send_shared_widget, edit_message_widget_data, edit_shared_widget_data

await send_shared_widget(client, chat_id, widget_id)
await edit_message_widget_data(client, chat_id=chat_id, message_id=msg["message_id"], public_data={"score": 10})
await edit_shared_widget_data(client, widget_id, public_data={"score": 11}, cache_time=30)
  • send_widget(client, chat_id, html, *, allow_queries=None, is_shared=None, width=None, height=None, ...) — html is checked against the documented 4096-byte (zlib level 9 compressed) limit before anything is sent (widget_html_compressed_size(html) to check it yourself).
  • send_shared_widget(client, chat_id, widget_id, ...) re-sends an existing shared widget, the way a photo is re-sent by file_id.
  • edit_message_widget_data(client, *, chat_id=None, message_id=None, inline_message_id=None, chat_data=None, public_data=None) — exactly one of (chat_id + message_id) or inline_message_id.
  • edit_shared_widget_data(client, widget_id, *, public_data=None, cache_time=None) — cache_time is 5–3600 seconds.
  • answer_widget_query(client, widget_query_id, data=None, *, received_at=None) — data is UTF-8 text up to 1024 bytes; pass received_at=time.time() (captured when the query arrived) to get an early ValueError instead of a late rejection if you're past Telegram's 15-second window.

All five raise WidgetAPIError (carrying .error_code/.description) on an ok: false Bot API response, and ValueError on a bad argument — unlike the rich-message senders above, they do not swallow failures into None.

Receiving widget_query / shared_widget_query

No known Pyrogram/Kurigram release parses these updates into Python objects yet, so there is no @client.on_widget_query()-style handler here. What nextgram provides instead is a parser for the raw Bot-API-JSON shape of the update — useful whether that JSON comes from a webhook, a getUpdates poll you run yourself, or (once a library adds support) an object a future Kurigram hands you:

from nextgram import extract_widget_query, answer_widget_query

query = extract_widget_query(update)  # update: a dict, or an object exposing .widget_query
if query is not None:
    await answer_widget_query(client, query.id, data="pong")

extract_widget_query accepts a whole update dict ({"update_id": ..., "widget_query": {...}}), a bare widget_query/shared_widget_query dict, or an object exposing .widget_query/.shared_widget_query, and returns a WidgetQuery, a SharedWidgetQuery, or None. Use parse_widget_query(data) / parse_shared_widget_query(data) directly if you already know which one you have.

A WidgetQuery carries id, from_user, chat_instance, widget_id, data (bytes), and either chat+message_id or inline_message_id. Its .wallet field is a WalletCard, WalletSentTransaction or WalletSignDataResult when the query is a TON Wallet response, parsed from the type payload the guide describes. A SharedWidgetQuery (from a forward of a shared widget) carries only id, from_user, widget_id and data.

TON Wallet transactions

from nextgram import build_wallet_transaction_answer

answer = build_wallet_transaction_answer(
    valid_until=int(time.time()) + 300,
    messages=[{"address": "EQ...", "amount": 1_000_000_000}],  # 1 TON, in nanotons
)

build_wallet_transaction_answer builds the TON Connect-shaped {valid_until, messages} object the guide describes for answering a wallet request; 1–255 messages, each amount normalised to a decimal nanoton string (validate_nanoton_amount).

Inline mode

input_widget_message_content(html, ...) and input_shared_widget_message_content(widget_id) build the InputWidgetMessageContent / InputSharedWidgetMessageContent dicts the guide names for answerInlineQuery; nextgram does not wrap answerInlineQuery itself (it already exists on Pyrogram/Kurigram clients), so pass these as one of the results there.

What this module does not cover, and why

  • As of this writing, core.telegram.org/bots/api (the full method/type reference) still tops out at Bot API 10.3 and does not list sendWidget. Everything above is built against the separate, already published guide page at core.telegram.org/bots/widgets, which does document these methods, fields and limits — but that page is a guide, not the full parameter-table reference other methods get, so a few parameters' exact required/optional status was not spelled out there. This module validates every limit the guide page does pin down and passes everything else through unchanged; see the docstring at the top of nextgram/widgets.py for the full list of what is, and isn't, confirmed.
  • Test server vs. production: this module does not special-case Telegram's test-server token namespace (.../bot<token>/test/...). Pass a test-server token via token=.../api_base=... and it behaves the same way, but size/rate limits and feature availability there are not guaranteed to match production, and this module cannot tell which one it's talking to.
  • Nothing here has been exercised against a live bot token or a real widget; the test suite (tests/unit/test_widgets.py) mocks the HTTP layer against the shapes the guide documents. Verify against a real bot before shipping.

Demo bot

bot.py is a small demo bot (/start with shuffling button colours):

API_ID=123 API_HASH=abc BOT_TOKEN=123:xyz python bot.py

Tests

pip install -e ".[test]"
pytest -m "unit or guard"

The unit tests use fake clients and messages, so they need no Telegram connection. tests/integrations sends a real message when API_ID, API_HASH, BOT_TOKEN and CHAT_ID are set.

Used by

Requirements

  • Python 3.10+
  • httpx, always required (a plain pip install nextgram pulls it in) — it's what nextgram.widgets and the aiogram/python-telegram-bot rich senders use for their direct Bot HTTP API calls.
  • Only the framework(s) you actually use — none of the other five are required to install or import nextgram:
    • Pyrogram / Pyrofork / Kurigram (pip install "nextgram[pyrogram]", or the matching fork directly — all three install as the same pyrogram package name). Native rich-message support (InputRichMessage/Client.send_rich_message) is used automatically when the installed build has it; RICH_AVAILABLE says whether it does. No known build has it yet, so the HTML fallback is what actually runs today.
    • Telethon >= 1.45 (pip install "nextgram[telethon]"). TELETHON_RICH_AVAILABLE says whether the installed build has the rich-message types.
    • aiogram >= 3.0 (pip install "nextgram[aiogram]").
    • python-telegram-bot >= 21.0 (pip install "nextgram[ptb]").
  • A bot token for widgets and for the aiogram/python-telegram-bot rich senders — passed as token=..., or read automatically from a client's .bot_token (Pyrogram/Pyrofork/Kurigram) or .token (aiogram, python-telegram-bot) attribute. Telethon has neither, so pass token=... explicitly when using it with nextgram.widgets.

Credits

  • Kurigram for Bot API 10.3 rich message support in the Pyrogram ecosystem. Full credit to the Kurigram developers.
  • nextgram by BadmundaXd.

Metadata

Release files for nextgram 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nextgram 0.9.0
File Size Uploaded Provenance Actions
nextgram-0.9.0.tar.gz 65.4 kB Without provenance Details for nextgram-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nextgram 0.9.0
File Interpreter ABI Platform Actions
nextgram-0.9.0-py3-none-any.whl Python 3 none any Details for nextgram-0.9.0-py3-none-any.whl

Total release size: 113.2 kB

Release files / nextgram-0.9.0.tar.gz

Download URL nextgram-0.9.0.tar.gz
Size 65.4 kB
Tags Source
SHA-256 checksum
How to use checksums
34ce30c2938f123f60299ec956082cbb17def7b647e3ee4d26641ebebe20ed22
BLAKE2b-256 checksum
How to use checksums
ab48d229e33fe40811e9d999eb4e0677eca7ecb900542ecb5ce7c6cbc6b820a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / nextgram-0.9.0-py3-none-any.whl

Download URL nextgram-0.9.0-py3-none-any.whl
Size 47.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c1968317f39b10b15e6393672f379630adc56143c240fcf7a4175d9e74330b30
BLAKE2b-256 checksum
How to use checksums
0f3528663adc0e20d94f9a1aea0e99146c744e811246193f43a2c93fb64d6cf8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for nextgram 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.9.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page