← All posts
Guide

Telegram Bot API 10.2 Upgrade Checklist: Rich Messages Media, Ephemeral Edits, and Communities

Telegram shipped Bot API 10.2 on July 14, 2026, and it is a larger code change than the version number suggests. Rich Messages gained media and block-level builders, ephemeral messages now have a full edit/delete method set, and Communities introduced a new topology to store. For a multi-platform team, the safe path is a pre-deploy checklist: pin the version, migrate the affected methods, and keep inbound normalization on a single webhook before you touch any production bot.

Key takeaways

  • 10.2 shipped July 14, 2026, adding rich message media, the full InputRichBlock* builder set, ephemeral edit/delete methods, and Community lifecycle messages — all officially documented on core.telegram.org.
  • Three breaking-adjacent changes need code review: the new media/blocks fields on InputRichMessage, receiver_user_id/ephemeral_message_id parameters on many send* methods, and the community_chat_added/community_chat_removed message types.
  • Rich Messages are outbound-only on the official Bot API. Inbound user messages still arrive as plain text/markdown — your inbound pipeline does not need to parse rich blocks unless you build a rich UI yourself.
  • Communities add routing state, not message merging. A Community links several supergroups, channels, and bots; messages still belong to their original chat IDs and must be routed per chat.
  • Do the upgrade behind a feature flag and verify your Bot API library has published a 10.2-compatible release before pointing production traffic at it.

What Bot API 10.2 actually changes

These are the verbatim additions from the official Bot API changelog, grouped by the area a team will actually need to touch.

Rich Messages: media and block builders

10.1 introduced Rich Messages — structured, AI-streamable formatted text. 10.2 makes them useful for real content:

  • Added the InputRichMessageMedia class and a media field to InputRichMessage, so a bot can “explicitly specify media used in markdown or html formatting when sending a rich message.”
  • Added the InputMediaVoiceNote class.
  • Added InputRichBlockListItem and the full set of input block classes: InputRichBlockParagraph, InputRichBlockSectionHeading, InputRichBlockPreformatted, InputRichBlockFooter, InputRichBlockDivider, InputRichBlockMathematicalExpression, InputRichBlockAnchor, InputRichBlockList, InputRichBlockBlockQuotation, InputRichBlockPullQuotation, InputRichBlockCollage, InputRichBlockSlideshow, InputRichBlockTable, InputRichBlockDetails, InputRichBlockMap, InputRichBlockAnimation, InputRichBlockAudio, InputRichBlockPhoto, InputRichBlockVideo, InputRichBlockVoiceNote, and InputRichBlockThinking.
  • Added the blocks field to InputRichMessage, letting a bot “specify rich message formatting via block entities.”

The practical effect: where 10.1 let you send a rich message, 10.2 lets you compose it from typed blocks and attach media. Any code that builds an InputRichMessage literal should be re-checked, because a library upgrade may now expect blocks instead of an inline string.

Ephemeral messages: full edit/delete lifecycle

Ephemeral messages (group messages visible only to one user and the bot) also arrived earlier, but 10.2 completes the method set:

  • Added is_ephemeral to BotCommand.
  • Added receiver_user and ephemeral_message_id to the Message class.
  • Added receiver_user_id and callback_query_id parameters to sendMessage, sendAnimation, sendAudio, sendDocument, sendLivePhoto, sendPhoto, sendSticker, sendVideo, sendVideoNote, sendVoice, sendContact, sendLocation, and sendVenue.
  • Added ephemeral_message_id to ReplyParameters (and made message_id optional when it is present).
  • Added editEphemeralMessageText, editEphemeralMessageMedia, editEphemeralMessageCaption, editEphemeralMessageReplyMarkup, and deleteEphemeralMessage.

If your support bot currently sends a private reply in a group and then cannot edit it, 10.2 is the upgrade that closes that gap. You already need to be a group administrator for this, as covered in the ephemeral message guide.

Communities: new message types

Communities are “several supergroups, channels, and bots linked together around a shared topic or audience.” For webhook consumers the key additions are:

  • The Community class.
  • CommunityChatAdded and CommunityChatRemoved message classes, plus their fields on Message.
  • A community field on ChatFullInfo.

These lifecycle messages are the same surface covered in the Communities event handling guide. For an upgrade checklist the rule is simpler: if your switch statement keys on message.text and falls through on unknown types, community_chat_added/community_chat_removed will silently hit the default branch. Add them explicitly so you can log Community topology changes.

General

  • Added BotSubscriptionUpdated (and a subscription field on Update) for user payment-subscription changes.
  • Strengthened Mini App security: methods from differing origins are disallowed, with automatic enforcement from July 20, 2026 (opt-out in BotFather).

Upgrade checklist

Work through this before flipping traffic to a 10.2 bot.

#ActionWhy it matters
1Pin your Bot API library to a 10.2-compatible release (e.g. Telegram.BotAPI 10.2.0 on .NET)Untyped or older clients will ignore the new fields and silently send degraded messages
2Audit every sendRichMessage / InputRichMessage constructionThe new media and blocks fields change how a rich message is composed
3Add community_chat_added / community_chat_removed to your message handlerUnknown message types hit the default branch and are lost
4Decide whether to adopt the new ephemeral edit/delete methodsLets a support bot correct a private reply without resending
5Store community on ChatFullInfo in your chat metadataNeeded to reason about Community topology later
6Test Mini App origin handling before July 20, 2026Cross-origin calls start being blocked on that date
7Keep inbound normalization on a single webhookRich blocks are outbound-only; inbound still arrives as plain text

What 10.2 does not change for inbound teams

The most important non-change: inbound messages from users still arrive as ordinary text. A user typing in a Telegram chat does not produce a RichMessage object on your end — Rich Messages are a bot-sending capability. This is the same conclusion from the earlier Bot API 10.1 analysis: the inbound problem is format normalization across platforms, not parsing rich blocks.

That means a team whose goal is receiving and triaging messages does not need to rewrite its inbound parser to adopt 10.2. The upgrade is about what your bot sends back.

Where UnifyPort fits

UnifyPort delivers inbound Telegram messages (alongside WhatsApp, LINE, X, Zalo, and TikTok) as one normalized message.received event stream, so the inbound side of a 10.2 upgrade — receiving the user’s message, verifying the HMAC-SHA256 signature, routing by conversation — stays unchanged regardless of the Bot API version.

The webhook event catalogue is stable: message.received, message.updated, message.deleted, message.read, message.reaction, plus conversation and account lifecycle events. Every delivery carries X-Device-Event-Id, X-Device-Delivery-Id, X-Device-Timestamp, and a hex-encoded X-Device-Signature (HMAC-SHA256 of "<timestamp>" + "." + "<raw body>") when the endpoint has a signing_secret. You verify with the raw body, parse the JSON, and branch on event.type — the webhook delivery and signature guide documents the exact verification routine.

If your upgrade goal is purely inbound reliability across platforms, you do not need to touch the official Bot API at all. If you also want to send rich or ephemeral replies from your own Telegram bot code, that is where the 10.2 changes apply — UnifyPort’s Telegram authorization covers the api_id / api_hash / phone flow that connects an account.

Limitations and trade-offs

  • Rich Messages need a compatible client. Users on very old Telegram clients may not render rich blocks; design fallbacks for plain text.
  • Ephemeral messages require group admin rights and only reach one user — they are not a broadcast tool.
  • Communities are new and evolving. Do not assume Community-level message aggregation exists today; route per chat ID and store topology as it arrives.
  • The official Bot API is still one platform. If your team also handles WhatsApp, LINE, or X inbound, adopting 10.2 only solves the Telegram side — the cross-platform inbound problem is separate.

FAQ

When was Bot API 10.2 released?

Telegram released Bot API 10.2 on July 14, 2026, per the official changelog at core.telegram.org/bots/api-changelog. The headline additions are Rich Message media and block builders, a full ephemeral message edit/delete method set, and Communities.

Do I have to upgrade immediately?

No deadline forces an upgrade for receiving messages. The one time-bound item is Mini App origin enforcement starting July 20, 2026; if you run a Mini App, test cross-origin behavior before that date.

Will inbound messages change format after 10.2?

No. Rich Messages are an outbound capability for bots. Inbound user messages still arrive as plain text or markdown, so your inbound parser does not need rich-block support.

Are Communities the same as group chats?

No. A Community is a set of linked supergroups, channels, and bots. Messages still belong to their original chat, and you route and store them per chat ID. The new community_chat_added and community_chat_removed message types let you track topology changes.

Can UnifyPort receive Telegram Community lifecycle events?

UnifyPort delivers Telegram inbound as normalized message.* and lifecycle events over its unified webhook. For Community-specific topology events, treat them the same way the Communities event guide describes — preserve the service-message fields and reconcile with getChat.

Next step

  • Review the webhook event catalogue to confirm your inbound handler already covers the standard message.* events: see the provider message support reference.
  • If you are connecting a Telegram account for the first time, the Quickstart walks through sending and receiving your first message.

Sources

  • Telegram Bot API changelog (official): https://core.telegram.org/bots/api-changelog — Bot API 10.2, July 14, 2026. Verified 2026-07-30.
  • Telegram Bot API reference (official): https://core.telegram.org/bots/api. Verified 2026-07-30.