Telegram Bot API 10.2: как обрабатывать добавление и удаление чатов Community
Telegram Communities в Bot API 10.2 объединяют несколько супергрупп, каналов и ботов вокруг одной темы. Когда текущий чат добавляют в Community, бот получает обычный Message с полем community_chat_added; при удалении приходит community_chat_removed. Рассматривайте их как события жизненного цикла: сохраняйте связь чата с Community, но маршрутизируйте сообщения по отдельным chat ID — Community не превращает связанные чаты в единый поток.
Главное
- Telegram представил Communities и начальную поддержку в Bot API 14 июля 2026 года.
community_chat_addedсодержит новый объектCommunity, аcommunity_chat_removedпока не содержит полей.- Оба сигнала находятся внутри сервисного
Message, а не в новых полях верхнего уровняUpdate. - Сохраняйте связь при добавлении: событие удаления не повторяет объект Community.
- Топология Telegram Community и очередь обращений из Telegram, WhatsApp, LINE, Zalo и других каналов — разные уровни системы.
Что именно появилось для Communities в Bot API 10.2
Согласно официальному анонсу Telegram, Community связывает группы, каналы и ботов вокруг общей темы. Участники могут видеть доступные чаты и вступать в них без отдельных пригласительных ссылок. Чат можно сделать скрытым: тогда он виден только его участникам и администраторам Community. По умолчанию участники могут добавлять чаты, но администратор может ограничить это право и превратить добавления в предложения.
В changelog Bot API 10.2 эта возможность названа начальной поддержкой. Текущий контракт небольшой:
| Поверхность Bot API | Что можно узнать | Чего она не даёт |
|---|---|---|
Message.community_chat_added | Текущий чат добавлен; доступен новый объект Community | Полную историю всех чатов Community |
Message.community_chat_removed | Текущий чат удалён | Из какого Community он удалён: объект пока пуст |
ChatFullInfo.community | Текущее Community для чата, возвращённое getChat, если оно есть | Общий inbox или единую модель прав для связанных чатов |
Это не то же самое, что эфемерные сообщения ботов в группах, где определяется видимость ответа. И это не Rich Messages из Bot API 10.1, где меняется формат сообщения. Communities описывают топологию чатов.
Как обработать community_chat_added и community_chat_removed
1. Проверьте, что клиент Bot API не теряет новые поля
Обновите типы или библиотеку до версии с поддержкой Bot API 10.2. Некоторые фреймворки удаляют неизвестные поля Message при десериализации. В таком случае Telegram доставит обновление, но обработчик не увидит Community-событие.
Если вы ограничиваете allowed_updates, оставьте как минимум message. Для Community с каналами отдельно проверьте channel_post в тестовой среде: Telegram добавил поля в общий тип Message, а не создал новый тип верхнего уровня. Не полагайтесь на название события, придуманное конкретной библиотекой, пока не посмотрите реальный Update.
2. Сохраните добавление до запуска фоновых задач
Этот обработчик Node.js использует только документированные поля и сохраняет объект Community целиком, не предполагая наличие неописанных вложенных свойств:
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,
});
}
}Используйте update_id как ключ идемпотентности. Telegram указывает, что идентификаторы обычно идут по порядку и помогают отбрасывать дубликаты или восстанавливать последовательность. Неполученные обновления хранятся не более 24 часов, поэтому очередь Bot API не заменяет вашу историю.
3. При удалении ищите старую связь по chat ID
CommunityChatRemoved сейчас является пустым объектом. Это главное ограничение реализации. Обработчик должен найти сохранённую связь по message.chat.id; получить идентификатор Community из события удаления невозможно.
Обе операции должны быть идемпотентными. Повторное добавление обновляет одну запись, а повторное удаление уже отсутствующей связи ничего не меняет. Для аудита можно сохранять исходный Update или краткую запись со временем изменения.
4. Сверяйте текущее состояние через getChat
В Bot API 10.2 объект ChatFullInfo, который возвращает getChat, получил необязательное поле community. Используйте его для сверки после переподключения webhook, обновления библиотеки или обнаружения пропуска в update_id. Постоянно опрашивать все чаты без причины не нужно.
В тестовом Community проверьте как минимум пять сценариев:
- Добавление супергруппы создаёт одну запись membership.
- Удаление очищает запись, хотя объект удаления пуст.
- Повторная доставка одного
update_idне меняет состояние дважды. getChatиChatFullInfo.communityсовпадают с кэшем.- Видимые и скрытые чаты работают с теми ролями администраторов, которые используются в продакшене.
Не смешивайте топологию Community с маршрутизацией сообщений
Community упрощает навигацию и организацию внутри Telegram, но не объединяет историю сообщений, права, chat ID или доступ бота.
| Задача | Источник истины |
|---|---|
| Чат добавлен в Telegram Community или удалён из него | Сервисные сообщения официального Bot API 10.2 и getChat |
| Бот получает обычные сообщения Telegram | Официальные Bot API Updates с учётом прав и privacy settings |
| Команда получает обращения из обычных аккаунтов нескольких платформ | Нормализованный входящий слой, например UnifyPort message.received |
Если служба поддержки одновременно работает в WhatsApp, LINE, Zalo, TikTok или X, Telegram Community не нормализует эти платформы. В статье о Telegram-автоматизации и межканальной входящей очереди подробнее разобрана граница между двумя уровнями.
Где здесь место UnifyPort
UnifyPort не создаёт Telegram Communities, не предоставляет CommunityChatAdded, не управляет видимостью чатов и не заменяет жизненный цикл официального Bot API. Для этих функций нужен официальный API Telegram.
UnifyPort решает другую задачу: приводит входящие сообщения обычных аккаунтов Telegram и других поддерживаемых платформ к одному стандартному потоку. Поддерживаемое сообщение приходит как message.received с полями конверта id, type, provider, account_id, occurred_at и data. Если у webhook endpoint задан signing_secret, доставку можно проверить по X-Device-Timestamp и HMAC-SHA256 в X-Device-Signature.
Храните уровни отдельно: membership Community — в таблице топологии Telegram, обращения клиентов — в очереди с ключами provider, account и conversation. Не преобразуйте community_chat_added в message.received: эти события описывают разные факты.
Ограничения и компромиссы
Bot API 10.2 предоставляет начальные данные о жизненном цикле, а не полный API управления Community. Объект удаления пуст, а исторический endpoint membership не заявлен. Поэтому интеграции нужны собственный кэш и тесты для фактических Update каждого типа чата.
Официальный Bot API подходит для ботов, сигналов Community, ролей Telegram и скрытых чатов. Неофициальный интерфейс не выдаёт эти официальные права и не переносит Community permissions на другие платформы. В то же время Community сам по себе не создаёт межканальную очередь обращений.
FAQ
Что такое Telegram Community в Bot API 10.2?
Это объединение нескольких супергрупп, каналов или ботов вокруг одной темы. Bot API 10.2 даёт начальную видимость через Community, community_chat_added, community_chat_removed и ChatFullInfo.community.
Где community_chat_added появляется в webhook?
Внутри Bot API Message, доставленного в Update. Это не новое поле верхнего уровня. Объект содержит новый Community, к которому относится текущий чат.
Какие данные содержит community_chat_removed?
Пока никаких. Telegram документирует CommunityChatRemoved как пустой объект, поэтому удаляйте сохранённую связь по текущему message.chat.id.
Объединяют ли Telegram Communities сообщения всех чатов?
Нет. Community организует обнаружение и membership, но каждый чат сохраняет свои сообщения, права, идентификаторы и требования к доступу бота.
Получает ли UnifyPort события жизненного цикла Community?
Текущий UnifyPort API Reference не описывает community_chat_added и community_chat_removed как стандартные события. Для Community используйте официальный Bot API, а для документированного нормализованного входящего потока — UnifyPort.
Следующий шаг
Если вам нужна межканальная очередь поддержки, сначала проверьте матрицу поддержки сообщений по провайдерам, затем реализуйте message.received по API Reference, не смешивая эти данные с состоянием Telegram Community.
Источники
Официальные источники проверены 26 июля 2026 года: