← Tất cả bài viết
Cẩm nang

Danh sách nâng cấp Telegram Bot API 10.2: phương tiện Rich Messages, chỉnh sửa Ephemeral và Communities

Telegram đã phát hành Bot API 10.2 vào ngày 14 tháng 7 năm 2026, và khối lượng thay đổi lớn hơn nhiều so với số phiên bản gợi ý. Rich Messages bổ sung phương tiện và trình xây dựng cấp block, ephemeral giờ có bộ phương thức chỉnh sửa/xóa hoàn chỉnh, và Communities đưa vào một cấu trúc liên kết mới cần lưu trữ. Với đội ngũ đa nền tảng, cách an toàn là đi qua danh sách trước khi triển khai: ghim phiên bản, di chuyển các phương thức bị ảnh hưởng và giữ chuẩn hóa tin nhắn đến trên một webhook duy nhất trước khi đụng đến bot đang chạy.

Điểm chính

  • 10.2 phát hành ngày 14 tháng 7 năm 2026, bổ sung media cho rich message, bộ trình xây dựng InputRichBlock*, phương thức chỉnh sửa/xóa ephemeral và tin nhắn vòng đời Communities — tất cả đều có trên tài liệu chính thức core.telegram.org.
  • Ba thay đổi gần breaking cần rà soát mã: trường media/blocks mới trên InputRichMessage, tham số receiver_user_id/ephemeral_message_id trên nhiều phương thức send*, và kiểu tin nhắn community_chat_added/community_chat_removed.
  • Rich Messages chỉ dùng cho outbound trong Bot API chính thức. Tin nhắn đến từ người dùng vẫn đến dạng văn bản thuần/markdown — luồng inbound của bạn không cần phân tích rich block trừ khi bạn tự xây giao diện phong phú.
  • Communities thêm trạng thái định tuyến, không phải gộp tin nhắn. Community liên kết nhiều supergroup, channel và bot; tin nhắn vẫn thuộc về chat ID ban đầu và phải được định tuyến theo từng chat.
  • Nâng cấp phía sau feature flag và xác nhận thư viện Bot API của bạn đã phát hành bản tương thích 10.2 trước khi trỏ lưu lượng production sang nó.

Bot API 10.2 thực sự thay đổi gì

Dưới đây là các bổ sung từng chữ từ changelog Bot API chính thức, được nhóm theo khu vực mà đội thực sự phải động đến.

Rich Messages: phương tiện và trình xây dựng block

10.1 giới thiệu Rich Messages — văn bản có cấu trúc, định dạng có thể stream AI. 10.2 cho phép chúng mang nội dung thực:

  • Thêm lớp InputRichMessageMedia và trường media trên InputRichMessage, để bot có thể “chỉ định rõ phương tiện dùng trong định dạng markdown hoặc html khi gửi rich message”.
  • Thêm lớp InputMediaVoiceNote.
  • Thêm InputRichBlockListItem và bộ lớp block đầu vào đầy đủ: InputRichBlockParagraph, InputRichBlockSectionHeading, InputRichBlockPreformatted, InputRichBlockFooter, InputRichBlockDivider, InputRichBlockMathematicalExpression, InputRichBlockAnchor, InputRichBlockList, InputRichBlockBlockQuotation, InputRichBlockPullQuotation, InputRichBlockCollage, InputRichBlockSlideshow, InputRichBlockTable, InputRichBlockDetails, InputRichBlockMap, InputRichBlockAnimation, InputRichBlockAudio, InputRichBlockPhoto, InputRichBlockVideo, InputRichBlockVoiceNote, InputRichBlockThinking.
  • Thêm trường blocks trên InputRichMessage, cho phép bot “chỉ định định dạng rich message qua các thực thể block”.

Hệ quả thực tế: nếu 10.1 cho phép bạn gửi rich message thì 10.2 cho phép lắp ráp nó từ các block có kiểu và đính kèm phương tiện. Bất kỳ mã nào xây InputRichMessage dạng literal đều nên kiểm tra lại, vì sau khi nâng cấp thư viện có thể mong đợi blocks thay vì chuỗi nội tuyến.

Ephemeral: vòng đời chỉnh sửa/xóa hoàn chỉnh

Tin nhắn ephemeral (tin nhóm chỉ hiển thị với một người dùng và bot) cũng xuất hiện trước đó, nhưng 10.2 hoàn thiện bộ phương thức:

  • Thêm is_ephemeral vào BotCommand.
  • Thêm receiver_user và ephemeral_message_id vào lớp Message.
  • Thêm tham số receiver_user_id và callback_query_id vào sendMessage, sendAnimation, sendAudio, sendDocument, sendLivePhoto, sendPhoto, sendSticker, sendVideo, sendVideoNote, sendVoice, sendContact, sendLocation, sendVenue.
  • Thêm ephemeral_message_id vào ReplyParameters (và làm cho message_id trở nên tùy chọn khi có nó).
  • Thêm editEphemeralMessageText, editEphemeralMessageMedia, editEphemeralMessageCaption, editEphemeralMessageReplyMarkup, deleteEphemeralMessage.

Nếu bot hỗ trợ của bạn hiện có thể gửi phản hồi riêng trong nhóm nhưng không thể chỉnh sửa, 10.2 chính là bản nâng cấp lấp khoảng trống đó. Bạn vẫn cần là quản trị viên nhóm — xem hướng dẫn tin nhắn ephemeral.

Communities: kiểu tin nhắn mới

Communities là “một số supergroup, channel và bot được liên kết quanh một chủ đề hoặc đối tượng chung”. Đối với người tiêu thụ webhook, bổ sung chính là:

  • Lớp Community.
  • Các lớp tin nhắn CommunityChatAdded và CommunityChatRemoved, cùng trường của chúng trên Message.
  • Trường community trên ChatFullInfo.

Các tin nhắn vòng đời này cùng giao diện với hướng dẫn xử lý sự kiện Communities. Đối với danh sách nâng cấp, quy tắc đơn giản hơn: nếu câu lệnh switch của bạn dùng message.text làm khóa và rơi vào nhánh mặc định với kiểu lạ, thì community_chat_added/community_chat_removed sẽ bị bỏ qua âm thầm. Xử lý chúng tường minh để ghi nhận thay đổi cấu trúc Community.

Chung

  • Thêm BotSubscriptionUpdated (và trường subscription trên Update) cho thay đổi đăng ký thanh toán của người dùng.
  • Tăng cường bảo mật Mini App: không cho phép phương thức từ origin khác nhau, tự động bật từ 20 tháng 7 năm 2026 (có thể opt-out trong BotFather).

Danh sách nâng cấp

Hoàn thành các mục này trước khi chuyển lưu lượng sang bot 10.2.

#Hành độngTại sao quan trọng
1Ghim thư viện Bot API ở bản tương thích 10.2 (ví dụ Telegram.BotAPI 10.2.0 trên .NET)Client không kiểu hoặc cũ sẽ bỏ qua trường mới và âm thầm gửi tin nhắn suy giảm
2Rà soát mọi cấu trúc sendRichMessage / InputRichMessageTrường media và blocks mới thay đổi cách lắp ráp rich message
3Thêm community_chat_added / community_chat_removed vào trình xử lý tin nhắnKiểu tin nhắn lạ rơi vào nhánh mặc định và bị mất
4Quyết định có áp dụng phương thức chỉnh sửa/xóa ephemeral mớiCho phép bot hỗ trợ sửa phản hồi riêng mà không cần gửi lại
5Lưu community từ ChatFullInfo trong siêu dữ liệu chatCần thiết để suy luận cấu trúc Community sau này
6Kiểm thử xử lý origin Mini App trước 20 tháng 7 năm 2026Từ ngày này các cuộc gọi cross-origin bắt đầu bị chặn
7Giữ chuẩn hóa inbound trên một webhook duy nhấtRich block chỉ dành cho outbound; inbound vẫn đến dạng văn bản

Những gì 10.2 không thay đổi cho đội inbound

Điều “không đổi” quan trọng nhất: tin nhắn đến từ người dùng vẫn đến dạng văn bản thường. Khi người dùng gõ trong chat Telegram, phía bạn không sinh ra đối tượng RichMessage — Rich Messages là khả năng bot gửi đi. Đây cũng là kết luận từ phân tích Bot API 10.1 trước đó: vấn đề inbound là chuẩn hóa định dạng đa nền tảng, chứ không phải phân tích rich block.

Nghĩa là, đội có mục tiêu nhận và phân luồng tin nhắn không cần viết lại trình phân tích cú pháp inbound để áp dụng 10.2. Bản nâng cấp này liên quan đến việc bot của bạn gửi lại cái gì.

Vị trí của UnifyPort

UnifyPort phân phối tin nhắn Telegram đến (cùng với WhatsApp, LINE, X, Zalo, TikTok) dưới dạng một luồng sự kiện message.received được chuẩn hóa thống nhất, nên phần inbound của bản nâng cấp 10.2 — nhận tin nhắn người dùng, xác minh chữ ký HMAC-SHA256, định tuyến theo hội thoại — vẫn không đổi bất kể phiên bản Bot API.

Danh mục sự kiện webhook ổn định: message.received, message.updated, message.deleted, message.read, message.reaction, cùng các sự kiện vòng đời hội thoại và tài khoản. Mỗi lần phân phối đều mang X-Device-Event-Id, X-Device-Delivery-Id, X-Device-Timestamp, và X-Device-Signature mã hóa hex (HMAC-SHA256 của "<dấu thời gian>" + "." + "<thân gốc>") khi endpoint có signing_secret. Bạn xác minh bằng thân gốc, phân tích JSON và rẽ nhánh theo event.type — quy trình xác minh chính xác được ghi trong hướng dẫn phân phối và chữ ký webhook.

Nếu mục tiêu nâng cấp của bạn thuần túy là độ tin cậy inbound đa nền tảng, bạn không cần đụng đến Bot API chính thức. Nếu bạn đồng thời muốn gửi phản hồi rich hoặc ephemeral từ mã bot Telegram của riêng mình, đó mới là nơi các thay đổi 10.2 áp dụng — ủy quyền Telegram của UnifyPort mô tả luồng api_id / api_hash / số điện thoại cần thiết để kết nối tài khoản.

Hạn chế và đánh đổi

  • Rich Messages cần client tương thích. Client Telegram rất cũ có thể không hiển thị rich block; hãy thiết kế phương án dự phòng văn bản thuần.
  • Tin nhắn ephemeral cần quyền quản trị viên nhóm và chỉ tiếp cận được một người dùng — đây không phải công cụ phát thanh.
  • Communities là tính năng mới và đang tiến hóa. Đừng giả định rằng việc tổng hợp tin nhắn cấp Community đã tồn tại hôm nay; định tuyến theo chat ID và lưu cấu trúc khi nó đến.
  • Bot API chính thức vẫn chỉ là một nền tảng. Nếu đội của bạn cũng xử lý inbound cho WhatsApp, LINE hoặc X, việc áp dụng 10.2 chỉ giải quyết phía Telegram — vấn đề inbound đa nền tảng cần xử lý riêng.

Câu hỏi thường gặp

Bot API 10.2 phát hành khi nào?

Telegram phát hành Bot API 10.2 vào ngày 14 tháng 7 năm 2026, theo changelog chính thức tại core.telegram.org/bots/api-changelog. Các bổ sung chính là phương tiện và trình xây dựng block của Rich Message, bộ phương thức chỉnh sửa/xóa ephemeral hoàn chỉnh, và Communities.

Tôi có phải nâng cấp ngay không?

Không có hạn chót nào ép nâng cấp tính năng nhận. Mục duy nhất có thời hạn là kiểm tra origin của Mini App bắt buộc từ ngày 20 tháng 7 năm 2026; nếu bạn chạy Mini App, hãy kiểm thử hành vi cross-origin trước ngày đó.

Định dạng tin nhắn inbound có thay đổi sau 10.2 không?

Không. Rich Messages là khả năng outbound của bot. Tin nhắn đến từ người dùng vẫn đến dạng văn bản thuần hoặc markdown, nên trình phân tích cú pháp inbound của bạn không cần hỗ trợ rich block.

Communities có giống với chat nhóm không?

Không. Community là tập hợp các supergroup, channel và bot được liên kết. Tin nhắn vẫn thuộc về chat ban đầu, và bạn định tuyến cùng lưu trữ theo chat ID. Các kiểu tin nhắn community_chat_added và community_chat_removed mới dùng để theo dõi thay đổi cấu trúc.

UnifyPort có nhận được các sự kiện vòng đời Community Telegram không?

UnifyPort phân phối Telegram đến dưới dạng các sự kiện message.* chuẩn hóa và sự kiện vòng đời trên webhook thống nhất. Đối với các sự kiện cấu trúc đặc thù của Community, xử lý theo cách mà hướng dẫn sự kiện Communities mô tả — giữ các trường service-message và đối chiếu bằng getChat.

Bước tiếp theo

  • Xem lại danh mục sự kiện webhook để xác nhận trình xử lý inbound của bạn đã bao phủ các sự kiện message.* chuẩn: xem tham chiếu provider message support.
  • Nếu bạn kết nối tài khoản Telegram lần đầu, Quickstart sẽ hướng dẫn bạn gửi và nhận tin nhắn đầu tiên.

Nguồn

  • Changelog Telegram Bot API (chính thức): https://core.telegram.org/bots/api-changelog — Bot API 10.2, 14-07-2026. Xác minh 30-07-2026.
  • Tham chiếu Telegram Bot API (chính thức): https://core.telegram.org/bots/api. Xác minh 30-07-2026.