Telegram Bot API 10.2 Communities：チャット追加・削除イベントの処理方法

Telegram Bot API 10.2 の Communities は、複数のスーパーグループ、チャンネル、ボットを一つのテーマで関連付ける機能です。現在のチャットが Community に追加されると、ボットは通常の Message 内で community_chat_added を受け取り、削除時には community_chat_removed を受け取ります。どちらも構成変更のシグナルとして保存し、メッセージ自体は従来どおり各 chat 単位で処理してください。Community が全チャットを一つの受信ストリームに統合するわけではありません。

要点

• Telegram は 2026 年 7 月 14 日に Communities と Bot API の初期サポートを公開しました。
• community_chat_added には新しい Community オブジェクトが入り、community_chat_removed は現時点で空です。
• どちらも Message のサービスメッセージ用フィールドであり、新しいトップレベル Update ではありません。
• 削除イベントから Community を復元できないため、追加時に chat との関係を保存します。
• Telegram 内の構成管理と、LINE・WhatsApp・Zalo などを含む顧客メッセージの統合は別レイヤーです。

Bot API 10.2 で確認できる Telegram Community の情報

Telegram の公式発表によると、Community は複数のグループ、チャンネル、ボットを共通テーマでまとめます。メンバーは公開されたチャットを個別の招待リンクなしで見つけて参加できます。チャットを非表示にし、そのチャットのメンバーと Community 管理者だけに見せる設定も可能です。初期設定ではメンバーもチャットを追加できますが、管理者は権限を制限し、提案として受け付けられます。

Bot API 10.2 はこれを「初期サポート」と表現しており、公開面は限定的です。

Bot API の項目	分かること	分からないこと
Message.community_chat_added	現在のチャットが追加され、新しい Community オブジェクトがある	Community 全体の変更履歴
Message.community_chat_removed	現在のチャットが削除された	どの Community から外れたか。現在は空オブジェクト
ChatFullInfo.community	getChat 時点で所属している Community（存在する場合）	全チャット共通の受信箱や権限

これは、返信を見られるユーザーを制御するTelegram のエフェメラル・ボットメッセージや、表示形式を扱う Bot API 10.1 Rich Messagesとは異なります。Communities が表すのはチャット間の構成です。

community_chat_added と community_chat_removed の実装

1. Bot API クライアントが新フィールドを保持するか確認する

Bot API 10.2 対応の型定義またはライブラリへ更新します。未知の Message フィールドをデシリアライズ時に捨てるフレームワークでは、Telegram がイベントを配信してもアプリには届いたように見えません。

allowed_updates を絞っている場合は、少なくとも message を残します。Community にチャンネルが含まれる場合は、テスト環境で channel_post も確認してください。公式仕様では Community の情報は共通の 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 は未取得の Update を最長 24 時間しか保持しないため、webhook キューを履歴データベースとして扱わないでください。

3. 削除時は chat ID から以前の関係を探す

CommunityChatRemoved は現在フィールドを持ちません。したがって、削除処理は message.chat.id で既存レコードを引き、空の削除オブジェクトから Community ID を取得しようとしてはいけません。

追加と削除はどちらも冪等にします。同じ追加を再受信したら同じレコードを更新し、既に削除済みの関係に対する再削除は何もしない設計が安全です。

4. getChat で現在値を照合する

Bot API 10.2 では getChat が返す ChatFullInfo に任意の community フィールドが追加されました。webhook の再接続、SDK 更新、update_id の欠落を検出したときにキャッシュと照合します。異常がない状態で全チャットを常時ポーリングする必要はありません。

非本番 Community で、スーパーグループの追加と削除、同一 update_id の再配信、getChat との照合、公開・非公開チャットを実際の管理者権限で試してください。

Community 構成とメッセージ経路を分離する

Community は Telegram 内の発見と整理を改善しますが、メッセージ履歴、権限、chat ID、ボットのアクセス権を統合しません。

要件	正しい情報源
Telegram Community への追加・削除	公式 Bot API 10.2 のサービスメッセージと getChat
ボットが通常の Telegram メッセージを受信	公式 Bot API Update とチャット権限
複数プラットフォームの通常アカウントから顧客メッセージを受信	UnifyPort message.received などの標準受信レイヤー

日本向けで LINE と Telegram を併用したり、さらに WhatsApp、Zalo、TikTok、X へ広げたりする場合、Telegram Community だけでは他チャネルを標準化できません。Telegram ネイティブ自動化とクロスチャネル受信キューのガイドで役割の違いを確認できます。

UnifyPort が担う範囲

UnifyPort は Telegram Communities を作成せず、CommunityChatAdded、Community の公開設定、公式 Bot API のライフサイクルも提供しません。これらが必要なら Telegram 公式 API を使用します。

UnifyPort が扱うのは別の要件です。Telegram と他の対応プラットフォームの通常アカウントから届くメッセージを、一つの標準イベントストリームにします。対応メッセージは message.received として届き、id、type、provider、account_id、occurred_at、data の共通エンベロープを持ちます。webhook endpoint に signing_secret を設定した場合、X-Device-Timestamp と X-Device-Signature で HMAC-SHA256 を検証できます。

Community membership は Telegram 構成テーブルに、顧客会話は provider・account・conversation をキーにしたキューへ保存します。community_chat_added を message.received に変換してはいけません。

制限とトレードオフ

Bot API 10.2 が提供するのは初期のライフサイクル情報で、完全な Community 管理 API ではありません。削除オブジェクトは空で、履歴照会も約束されていないため、アプリ側のキャッシュと実環境に近いテストが必要です。

ボット、Community の関係、Telegram 固有の権限と非公開チャットには公式 Bot API が適しています。非公式インターフェースはこれらの公式権限を付与できません。一方、Community だけでは Telegram 以外の統合受信キューを作れません。

よくある質問

Bot API 10.2 の Telegram Community とは何ですか？

複数のスーパーグループ、チャンネル、ボットを一つのテーマで関連付ける仕組みです。Bot API 10.2 は Community、追加・削除サービスメッセージ、ChatFullInfo.community を公開しました。

community_chat_added は webhook のどこにありますか？

Update 内の Bot API Message にあります。トップレベル Update の新フィールドではなく、現在のチャットが所属する Community を含みます。

community_chat_removed には何が入りますか？

現在は何も入りません。message.chat.id を使って、以前保存した関係を削除します。

Communities は全チャットのメッセージを統合しますか？

いいえ。各チャットは独自のメッセージ、権限、識別子、ボットアクセス条件を維持します。

UnifyPort で Community のライフサイクルを受信できますか？

現在の UnifyPort API Reference はこの二つを標準イベントとして定義していません。Community の変更は公式 Bot API、標準化された受信メッセージは UnifyPort の文書化済みイベントを使用します。

次のステップ

目的がクロスチャネルの顧客対応キューなら、プロバイダー別メッセージ対応表を確認し、message.received API Referenceに沿って実装してください。Telegram Community の状態とは別に管理します。

参照元

公式情報の確認日：2026 年 7 月 26 日。

• Telegram：Communities 発表
• Telegram Bot API 10.2 と Community 型
• Telegram：CommunityChatAdded
• Telegram：CommunityChatRemoved
• Telegram：setWebhook