Tutorial July 26, 2026

Telegram Communities in Bot API 10.2: Handle Chat Added and Removed Events

Telegram Communities in Bot API 10.2 link several supergroups, channels, and bots around one topic. A bot learns that its current chat joined a community through a normal Message containing community_chat_added; removal appears as community_chat_removed. Treat both as lifecycle signals, cache the chat-to-community mapping, and keep normal message routing keyed by chat—Communities do not create one shared message stream.

Key takeaways

Telegram launched Communities and initial Bot API support on July 14, 2026.
community_chat_added carries a Community object, while community_chat_removed currently carries no fields.
Both are service-message fields inside Message, not new top-level Update types.
Cache the relationship when a chat is added, because the removal signal does not repeat the community object.
Telegram Community topology and a cross-channel customer-message queue are different layers and should be stored separately.

What Telegram Communities add in Bot API 10.2

Telegram’s July 14 announcement describes a Community as several groups, channels, or bots linked around a shared topic. Members can discover and join visible chats without separate invite links. Chats can also be hidden from everyone except their own members and Community administrators. By default, members can add chats, although administrators can restrict that behavior so additions become suggestions.

Bot API 10.2 calls its support initial support. The current official surface is intentionally small:

Bot API surface	What it tells you	What it does not tell you
`Message.community_chat_added`	The current chat was added, plus its new `Community` object	A complete event history for every chat in the Community
`Message.community_chat_removed`	The current chat was removed	Which Community it left; the object currently has no fields
`ChatFullInfo.community`	The Community to which the queried chat currently belongs, when available	A universal inbox or permission model for every linked chat

This is separate from Telegram ephemeral bot messages, which control who can see a bot response, and from Bot API 10.1 Rich Messages, which control message formatting. Communities describe chat topology.

How to handle community_chat_added and community_chat_removed

1. Preserve service-message fields in your Bot API client

Upgrade your Bot API types or library to a version that understands Bot API 10.2. If your framework drops unknown Message fields during deserialization, it can silently discard both Community signals even though Telegram delivered them.

If you restrict allowed_updates, retain message. Also test channel_post when a Community contains channels, because Telegram documents the Community fields on the shared Message type rather than as a new top-level update. Do not assume a library-specific event name until you have inspected a real update from a test Community.

2. Store the add event before doing downstream work

The following Node.js handler uses only the fields Telegram currently documents. It stores the complete Community object without inventing nested properties:

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,
    });
  }
}

Persist update_id as an idempotency key. Telegram says update identifiers are sequential in normal operation and useful for ignoring duplicates or restoring order. It also retains unconsumed updates for no longer than 24 hours, so a database record is safer than treating the webhook queue as history.

3. Remove by chat ID, not by a field that is absent

CommunityChatRemoved currently holds no information. That is the critical implementation boundary. Your removal handler must look up the previous relationship by message.chat.id; it cannot read a Community identifier from the removal object.

Make add and remove operations idempotent. A duplicate add should update the same membership, and a duplicate removal should be a no-op after the relationship is gone. Keep the raw update or an audit summary if administrators need to explain when topology changed.

4. Reconcile current state with getChat

Bot API 10.2 adds the optional community field to ChatFullInfo, returned by getChat. Use it as a current-state check after reconnecting a webhook, upgrading a library, or detecting a gap in update_id values. Do not poll every chat continuously; reconcile when there is a reason to doubt the cached mapping.

Test at least these transitions in a non-production Community:

Add a supergroup and confirm one membership record appears.
Remove it and confirm the cached record is deleted even though the removal object is empty.
Repeat delivery of the same update_id and confirm state does not change twice.
Query getChat and compare ChatFullInfo.community with the stored result.
Test visible and hidden chats with the roles your real administrators use.

Keep Community topology separate from message routing

A Community makes related Telegram chats easier to discover and organize. It does not merge their message histories, webhook identifiers, permissions, or bot access into one conversation.

Concern	Correct source of truth
Chat was added to or removed from a Telegram Community	Official Bot API 10.2 service messages and `getChat`
Bot receives normal messages in a Telegram chat	Official Bot API updates, subject to bot access and privacy settings
Team receives customer messages from ordinary accounts across several platforms	A normalized inbound layer such as UnifyPort `message.received`

The distinction matters when a support team also uses WhatsApp, LINE, Zalo, TikTok, or X. A Telegram Community can group Telegram surfaces, but it does not normalize those other providers. The existing Telegram chat automation guide explains why Telegram-native organization and a cross-channel queue solve different problems.

Where UnifyPort fits

UnifyPort does not create Telegram Communities, expose CommunityChatAdded, manage Community visibility, or replace the official Bot API lifecycle. Use Telegram’s official API when your application needs those features.

UnifyPort fits after a different decision: when ordinary-account inbound messages from Telegram and other supported providers need one standard event stream. A supported message arrives as message.received with the envelope id, type, provider, account_id, occurred_at, and data. If the webhook endpoint has a signing_secret, delivery uses X-Device-Timestamp and X-Device-Signature for HMAC-SHA256 verification.

Store the two layers independently: Community membership in a Telegram-topology table, and customer conversations in the queue keyed by provider, account, and conversation. Do not transform community_chat_added into message.received; they describe different facts.

Limitations and trade-offs

Bot API 10.2 exposes initial Community lifecycle data, not a complete Community-management API. The removal object is empty, and the public documentation does not promise a historical membership endpoint. Your integration must therefore keep its own cache and test the actual update envelope used by each chat type.

The official Bot API is the right choice for bots, Community membership signals, Telegram-native roles, and hidden-chat behavior. An unofficial interface cannot grant those official privileges or combine Community permissions across platforms. Conversely, a Community alone does not give a support team a normalized inbound queue outside Telegram.

FAQ

What is a Telegram Community in Bot API 10.2?

A Community links several Telegram supergroups, channels, or bots around one topic. Bot API 10.2 provides initial lifecycle visibility through Community, community_chat_added, community_chat_removed, and ChatFullInfo.community.

Where does community_chat_added appear in a webhook?

It appears inside a Bot API Message delivered in an update. It is not a new top-level Update field. The object contains the new Community to which the current chat belongs.

What data does community_chat_removed contain?

None at present. Telegram documents CommunityChatRemoved as an empty object, so remove the cached relationship by the current message.chat.id.

Do Telegram Communities merge messages from every linked chat?

No. Communities organize discovery and membership. Each chat keeps its own messages, permissions, and identifiers, and a bot still needs access to each relevant chat.

Can UnifyPort receive Telegram Community lifecycle events?

The current UnifyPort API reference does not document community_chat_added or community_chat_removed as standard events. Use the official Bot API for Community lifecycle and UnifyPort for its documented normalized inbound-message layer.

Next step

If your real goal is a cross-channel support queue, check the provider message-support matrix and then implement the message.received API reference without mixing it with Telegram Community state.

Sources

Official sources checked on July 26, 2026: