Choosing Telegram Widgets: an interactive-message requirements checklist

When a bot needs an interactive status card, start with the user's job rather than a request to put a website inside Telegram. A clear status and two buttons may already solve the problem. A richer card should earn its complexity by making information easier to understand or act on.

Telegram's official Widgets guide describes an interface embedded in a message. Its lifecycle makes older messages an important part of release planning. This article proposes requirements and acceptance checks; it is neither a delivered client case nor a BotFatherV2 feature announcement.

Decide what the card helps a person do

Consider a hypothetical personal progress tracker. Someone opens a record, reads its current stage and update time, then performs an allowed next action. The first version has three jobs: explain the status, reveal the available action, and confirm whether it completed.

Use this decision sequence:

1. If one line and a few fixed actions are enough, start with a normal message and buttons. A replacement interface should improve an observable outcome, such as reducing misunderstandings.
2. If several states need a strong visual relationship or graphical feedback, evaluate a Widget. Give every visual element a purpose before adding animation.
3. If the job needs long forms, extensive navigation, or multiple screens, assess it as a separate application interface rather than compressing the whole workflow into a chat message.

These are scope decisions, not evidence that a particular builder supports the chosen technology.

Check the documented Telegram boundary first

Checked November 11, 2026, the official guide describes self-contained HTML running in a network-free sandbox. The bot writes changing state; the sent HTML stays fixed, so a new layout needs a new Widget. Current production support is limited to private chats with the bot; broader group, inline, and forwarding scenarios belong to the test environment. Widgets differ from Mini Apps, and their documented input does not include a keyboard.

A successful test-group demonstration therefore cannot establish production-group support. Specify the environment, chat type, and target clients before implementation, then verify those exact combinations at acceptance.

Separate visibility from bubble layout

“Keep the status visible” can mean three different outcomes:

• A person can find the record again.
• Expanding the card preserves a useful reading position.
• The card remains fixed in the viewport as new chat messages arrive.

The guide makes CSS fixed positioning relative to the bubble; setResizeAnchor chooses the bubble edge preserved during resizing. Neither is a promise of permanent chat-bottom placement or pinning.

A more useful first requirement might be that /status provides the latest valid record entry, while an older entry either remains interpretable or explains that it has been replaced. Finding a record and keeping it permanently floating should not be one acceptance condition.

Agree on business state before drawing the interface

For the hypothetical tracker, define a record identifier, state revision, and permitted actions before choosing the layout. The following are proposed business rules:

1. Pending means the request is being processed. Completion appears only after the bot confirms the business update.
2. An action from an older card must be checked against current state and the operator's authority. A visible button does not establish current permission.
3. Missing records, expired actions, permission failures, and technical failures need distinct, understandable results.
4. Reopening an old message should make it possible to distinguish current state from a historical snapshot. Show update times where freshness matters.
5. Before displaying one record in several places, decide which fields can be shared and which belong only to the current user.

The work here is defining the relationship between the interface and the record. It does not require another general retry or authorization framework. The existing button-action acceptance guide can help review the underlying operation.

Plan for old cards after a bot update

Because sent interface code is fixed, write a compatibility inventory: what older cards may submit, which fields older data lacks, what the new backend still understands, and when the user must open a newer entry.

For example, splitting one processing stage into two must not make an older interface interpret an unknown stage as completed. Design an understandable older-version outcome and a route to the latest record. Verify that the older code can actually display that outcome; adding a new backend response does not create a missing branch in an already-sent interface.

Include old messages in rollback tests too. Restoring bot code and replacing previously sent interfaces are different release jobs.

An editable brief and acceptance checklist

This is a proposal to assess, not a product configuration recipe:

Design a personal record-status interface. Deliver normal messages and buttons first, then assess Widgets separately. Use verified environments only; do not promise production group or inline support. Associate each card with a record and revision, and display state and update time. Recheck authority and current business state before actions. Distinguish pending, success, permission denial, expiry, and failure. Document compatibility between older interfaces and the new backend. If the current SDK lacks a required method or event, retain the ordinary-message version and list the unsupported requirement.

Record at least these acceptance cases:

• First open, close and reopen, and finding the message after scrolling on target clients in a real production private chat.
• Actions against the same record from new and older cards, with consistent and understandable outcomes.
• State changes, stale display values, and failures that must not appear as success.
• Light and dark themes, narrow screens, and long text, with readable status and discoverable actions.
• New incoming chat messages, checking actual positioning rather than mistaking bubble layout for chat-level persistence.
• Upgrades and code rollbacks, including old entries, unknown states, and unsupported environments.

These are tests to execute. No Widget was deployed or tested for this article.

Applying this to BotFatherV2

BotFatherV2 supports creating and modifying Telegram bots through AI conversation, version publishing, importing existing Telegram Serverless bots, and code rollback that preserves current business data. The interaction and compatibility requirements above can be a starting point for discussion.

However, the public help documentation checked here does not establish that its fixed SDK supports Widget sending methods and events. Telegram platform support must not become a claim of an existing BotFatherV2 feature. Arbitrary npm modules and Node/Bun runtime APIs are outside the validator's fixed surface. AI-assisted development also does not imply an autonomous runtime agent. A network-free Widget does not establish any external API or model service in its bot backend.

The next step is to list required methods, events, and deployment environments, then verify SDK support. Keep the normal-message version if those checks fail, or assess a custom implementation separately. BotFatherV2 is independent and is not affiliated with Telegram's official BotFather.

Sources and verification

• Telegram: Telegram Widgets, official English design and interface documentation, no fixed publication date shown; checked November 11, 2026. Recheck production scope and interfaces before implementation.
• BotFatherV2: public English homepage and Build with AI, checked the same day as capability and support-boundary evidence.