Telegram Bot API 10.2 Communities: Xử lý sự kiện thêm và gỡ chat

Telegram Communities trong Bot API 10.2 liên kết nhiều supergroup, channel và bot theo cùng một chủ đề. Khi chat hiện tại được thêm vào Community, bot nhận một Message thông thường có community_chat_added; khi bị gỡ, bot nhận community_chat_removed. Hãy xem đây là tín hiệu vòng đời cấu trúc: lưu quan hệ giữa chat và Community, nhưng vẫn định tuyến tin nhắn theo từng chat ID vì Community không tạo ra một luồng tin nhắn dùng chung.

Điểm chính

• Telegram ra mắt Communities và hỗ trợ Bot API ban đầu vào ngày 14/7/2026.
• community_chat_added chứa đối tượng Community mới; community_chat_removed hiện không có trường dữ liệu.
• Cả hai là trường service message bên trong Message, không phải loại Update cấp cao nhất mới.
• Phải lưu quan hệ ngay khi thêm vì sự kiện gỡ không gửi lại đối tượng Community.
• Cấu trúc Telegram Community và hàng đợi hỗ trợ khách hàng từ Telegram, Zalo, WhatsApp hay LINE là hai lớp khác nhau.

Bot API 10.2 cung cấp gì cho Telegram Communities

Theo thông báo chính thức của Telegram, Community liên kết các group, channel và bot xoay quanh một chủ đề. Thành viên có thể tìm và tham gia chat hiển thị mà không cần từng invite link riêng. Chat cũng có thể bị ẩn với mọi người trừ thành viên của chính chat đó và quản trị viên Community. Mặc định thành viên có thể thêm chat; quản trị viên có thể hạn chế quyền này để chuyển thao tác thêm thành đề xuất.

Bot API 10.2 gọi đây là hỗ trợ ban đầu. Phạm vi hiện tại khá nhỏ:

Bề mặt Bot API	Cho biết	Không cho biết
Message.community_chat_added	Chat hiện tại đã được thêm và có đối tượng Community mới	Lịch sử đầy đủ của mọi chat trong Community
Message.community_chat_removed	Chat hiện tại đã bị gỡ	Community nào đã bị rời; đối tượng hiện rỗng
ChatFullInfo.community	Community hiện tại do getChat trả về, nếu có	Inbox chung hay mô hình quyền dùng chung

Tính năng này khác với tin nhắn bot tạm thời trong group Telegram, vốn kiểm soát ai nhìn thấy câu trả lời, và khác với Bot API 10.1 Rich Messages, vốn kiểm soát định dạng. Communities mô tả cấu trúc liên kết giữa các chat.

Cách xử lý community_chat_added và community_chat_removed

1. Đảm bảo client Bot API không làm mất trường mới

Cập nhật type hoặc thư viện lên phiên bản hiểu Bot API 10.2. Nếu framework loại bỏ trường Message chưa biết khi deserialize, Telegram vẫn giao Update nhưng ứng dụng sẽ không nhìn thấy tín hiệu Community.

Nếu giới hạn allowed_updates, hãy giữ ít nhất message. Với Community có channel, cần kiểm thử cả channel_post, vì Telegram đặt các trường mới trên kiểu Message dùng chung chứ không tạo Update cấp cao nhất riêng.

2. Lưu sự kiện thêm ngay khi nhận được

Đoạn Node.js sau chỉ dùng các trường Telegram đang mô tả và lưu nguyên đối tượng Community, không tự đặt tên cho thuộc tính bên trong:

async function handleTelegramUpdate(update, store) {
  const message = update.message ?? update.channel_post;
  if (!message) return;

  if (message.community_chat_added) {
    await store.upsertCommunityMembership({
      chatId: String(message.chat.id),
      community: message.community_chat_added.community,
      updateId: update.update_id,
      observedAt: new Date(message.date * 1000).toISOString(),
    });
  }

  if (Object.hasOwn(message, "community_chat_removed")) {
    await store.removeCommunityMembership({
      chatId: String(message.chat.id),
      updateId: update.update_id,
    });
  }
}

Lưu update_id làm khóa idempotency. Telegram cho biết ID thường tăng tuần tự và hữu ích để bỏ bản sao hoặc khôi phục thứ tự. Update chưa được nhận chỉ được giữ tối đa 24 giờ, vì vậy hàng đợi webhook không thay thế lịch sử riêng của bạn.

3. Khi gỡ, tra quan hệ cũ bằng chat ID

CommunityChatRemoved hiện là đối tượng rỗng. Handler phải tìm quan hệ đã lưu bằng message.chat.id; không thể đọc Community ID từ sự kiện gỡ. Việc thêm và gỡ đều nên idempotent: thêm lặp chỉ cập nhật cùng một bản ghi, gỡ lặp sau khi đã xóa sẽ không làm gì.

4. Đối soát trạng thái bằng getChat

Trong Bot API 10.2, ChatFullInfo do getChat trả về có thêm trường community tùy chọn. Hãy dùng nó để đối soát sau khi webhook kết nối lại, thư viện được nâng cấp hoặc phát hiện khoảng trống update_id; không cần polling mọi chat liên tục.

Trong Community thử nghiệm, cần kiểm tra thêm supergroup, gỡ group, giao lại cùng update_id, so sánh với getChat, và cả chat hiển thị lẫn chat ẩn dưới vai trò quản trị thật.

Tách cấu trúc Community khỏi định tuyến tin nhắn

Community giúp khám phá và tổ chức chat trong Telegram, nhưng không hợp nhất lịch sử tin nhắn, quyền, chat ID hoặc quyền truy cập của bot.

Nhu cầu	Nguồn dữ liệu đúng
Chat được thêm hoặc gỡ khỏi Telegram Community	Service message chính thức của Bot API 10.2 và getChat
Bot nhận tin nhắn Telegram thông thường	Bot API Update chính thức, theo quyền của chat
Đội ngũ nhận tin khách hàng từ tài khoản thường trên nhiều nền tảng	Lớp inbound chuẩn hóa như UnifyPort message.received

Với đội ngũ Việt Nam xử lý Zalo cùng Telegram, WhatsApp hoặc LINE, Community chỉ sắp xếp bề mặt Telegram và không chuẩn hóa nền tảng khác. Hướng dẫn Telegram automation và hàng đợi đa kênh giải thích rõ ranh giới này.

UnifyPort nằm ở đâu

UnifyPort không tạo Telegram Communities, không cung cấp CommunityChatAdded, không quản lý quyền hiển thị Community và không thay thế vòng đời Bot API chính thức. Khi cần các tính năng đó, hãy dùng API chính thức của Telegram.

UnifyPort giải quyết bài toán khác: đưa tin nhắn inbound từ tài khoản Telegram thông thường và các nền tảng được hỗ trợ vào một luồng sự kiện chuẩn. Tin nhắn hợp lệ đến dưới dạng message.received với envelope gồm id, type, provider, account_id, occurred_at và data. Khi webhook endpoint có signing_secret, có thể xác minh HMAC-SHA256 bằng X-Device-Timestamp và X-Device-Signature.

Hãy lưu Community membership trong bảng cấu trúc Telegram, còn hội thoại khách hàng trong queue theo provider, account và conversation. Không chuyển community_chat_added thành message.received vì chúng mô tả hai sự kiện khác nhau.

Giới hạn và đánh đổi

Bot API 10.2 chỉ cung cấp dữ liệu vòng đời ban đầu, chưa phải API quản lý Community hoàn chỉnh. Đối tượng gỡ rỗng và không có cam kết về endpoint lịch sử, nên ứng dụng cần cache riêng và kiểm thử Update thật cho từng loại chat.

Bot API chính thức là lựa chọn đúng cho bot, Community, vai trò Telegram và chat ẩn. Giao diện không chính thức không thể cấp những quyền chính thức này. Ngược lại, Community cũng không tạo hàng đợi inbound thống nhất bên ngoài Telegram.

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

Telegram Community trong Bot API 10.2 là gì?

Đó là cách liên kết nhiều supergroup, channel hoặc bot theo một chủ đề. Bot API 10.2 cung cấp khả năng quan sát ban đầu qua Community, hai service message thêm/gỡ và ChatFullInfo.community.

community_chat_added nằm ở đâu trong webhook?

Nó nằm trong Bot API Message được giao trong Update, không phải trường Update cấp cao nhất mới. Đối tượng này chứa Community mới của chat hiện tại.

community_chat_removed chứa dữ liệu gì?

Hiện không có trường nào. Hãy xóa quan hệ đã lưu bằng message.chat.id của chat hiện tại.

Communities có hợp nhất tin nhắn của mọi chat không?

Không. Mỗi chat vẫn có tin nhắn, quyền, định danh và điều kiện truy cập bot riêng.

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

UnifyPort API Reference hiện không mô tả hai trường này là sự kiện chuẩn. Dùng Bot API chính thức cho Community và dùng UnifyPort cho lớp inbound chuẩn hóa đã được tài liệu hóa.

Bước tiếp theo

Nếu mục tiêu là hàng đợi hỗ trợ đa kênh, hãy kiểm tra ma trận hỗ trợ tin nhắn theo provider rồi triển khai theo message.received API Reference, tách biệt với trạng thái Telegram Community.

Nguồn

Nguồn chính thức được kiểm tra ngày 26/7/2026:

• Telegram: thông báo Communities
• Telegram Bot API 10.2 và kiểu Community
• Telegram: CommunityChatAdded
• Telegram: CommunityChatRemoved
• Telegram: setWebhook