← 全記事
ガイド

Telegram Bot API 10.2 アップグレードチェックリスト：Rich Messages メディア、Ephemeral 編集、Communities 対応

Telegram は 2026 年 7 月 14 日に Bot API 10.2 を公開しました。バージョン番号が示すより変更幅は大きいのが特徴です。Rich Messages にメディアとブロック単位のビルダーが追加され、Ephemeral メッセージに編集／削除のメソッド群が揃い、Communities という格納すべき新しいトポロジーが導入されました。複数プラットフォームを扱うチームは、本番のボットに触る前にまずチェックリストを進めるのが安全な順序です。バージョンを固定し、影響を受けるメソッドを移行し、inbound の正規化は単一の webhook に置いたままにします。

ポイント

  • 10.2 は 2026 年 7 月 14 日公開で、rich message の media、InputRichBlock* ビルダー群、ephemeral 編集／削除メソッド、Communities のライフサイクルメッセージが追加されました。いずれも core.telegram.org の公式ドキュメントに記載されています。
  • 破壊的変更に近い 3 箇所を確認する必要があります。InputRichMessage の新 media/blocks フィールド、複数の send* メソッドに増えた receiver_user_id/ephemeral_message_id パラメータ、そして community_chat_added/community_chat_removed のメッセージ型です。
  • Rich Messages は公式 Bot API では送信専用です。 ユーザーからの inbound は引き続きプレーンテキスト／markdown で届くため、独自にリッチ UI を組まない限り inbound パイプラインが rich block を解析する必要はありません。
  • Communities が増やすのはルーティングの状態で、メッセージの統合ではありません。 Community は複数の supergroup・channel・bot を束ねるものであり、メッセージ自体は元の chat ID に属し続け、chat ごとにルーティングします。
  • 機能フラグの後ろでアップグレードし、使用中の Bot API ライブラリが 10.2 対応版を出していることを確認してから本番トラフィックを切り替えましょう。

Bot API 10.2 で実際に変わったこと

以下は公式 Bot API changelog の記載内容を、チームが実際に触れる領域ごとに整理したものです。

Rich Messages：メディアとブロックビルダー

10.1 で Rich Messages（構造化された AI ストリーミング対応の書式付きテキスト）が入りました。10.2 では実コンテンツを扱えるようになります。

  • InputRichMessageMedia クラスと、InputRichMessage の media フィールドが追加され、ボットは「rich message を送る際に markdown や html 内で使うメディアを明示指定」できるようになりました。
  • InputMediaVoiceNote クラスが追加されました。
  • InputRichBlockListItem と、入力用ブロッククラス群（InputRichBlockParagraph、InputRichBlockSectionHeading、InputRichBlockPreformatted、InputRichBlockFooter、InputRichBlockDivider、InputRichBlockMathematicalExpression、InputRichBlockAnchor、InputRichBlockList、InputRichBlockBlockQuotation、InputRichBlockPullQuotation、InputRichBlockCollage、InputRichBlockSlideshow、InputRichBlockTable、InputRichBlockDetails、InputRichBlockMap、InputRichBlockAnimation、InputRichBlockAudio、InputRichBlockPhoto、InputRichBlockVideo、InputRichBlockVoiceNote、InputRichBlockThinking）が追加されました。
  • InputRichMessage に blocks フィールドが追加され、「ブロックエンティティで rich message の書式を指定」できるようになりました。

実務上の影響：10.1 は rich message を「送れる」ようにしただけであれば、10.2 は型付きブロックで組み立ててメディアを添付できるようにします。InputRichMessage をリテラルで直接構築している箇所はすべて再確認してください。ライブラリ更新後は blocks を期待する可能性があるためです。

Ephemeral メッセージ：編集／削除のライフサイクル完備

Ephemeral メッセージ（1 ユーザーとボットにだけ見えるグループメッセージ）も以前から存在しましたが、10.2 でメソッド群が完成します。

  • BotCommand に is_ephemeral が追加されました。
  • Message クラスに receiver_user と ephemeral_message_id が追加されました。
  • sendMessage、sendAnimation、sendAudio、sendDocument、sendLivePhoto、sendPhoto、sendSticker、sendVideo、sendVideoNote、sendVoice、sendContact、sendLocation、sendVenue に receiver_user_id と callback_query_id パラメータが追加されました。
  • ReplyParameters に ephemeral_message_id が追加され（存在する場合は message_id が任意になりました）。
  • editEphemeralMessageText、editEphemeralMessageMedia、editEphemeralMessageCaption、editEphemeralMessageReplyMarkup、deleteEphemeralMessage が追加されました。

サポートボットが現在グループ内で個別返信できても編集できない場合、10.2 がその穴を埋めるアップグレードです。引き続きグループ管理者権限が必要です。詳しくは Ephemeral メッセージガイド を参照してください。

Communities：新しいメッセージ型

Communities は「共通のトピックや読者の周りに複数の supergroup・channel・bot を束ねたもの」です。webhook の利用者にとって重要な追加は次のとおりです。

  • Community クラス。
  • CommunityChatAdded と CommunityChatRemoved のメッセージクラスと、それらの Message フィールド。
  • ChatFullInfo の community フィールド。

これらのライフサイクルメッセージは Communities イベント処理ガイド で扱っているものと同じインターフェースです。アップグレードチェックリストとしてのルールはより単純です。switch 文が message.text をキーにしていて未知の型が default に落ちる作りなら、community_chat_added/community_chat_removed は黙って捨てられます。明示的に処理して Community のトポロジー変更を記録できるようにしましょう。

その他

  • ユーザーの支払いサブスクリプション変更を表す BotSubscriptionUpdated（と Update の subscription フィールド）が追加されました。
  • Mini App のセキュリティ強化：異なる origin からのメソッド呼び出しを禁止し、2026 年 7 月 20 日から自動的に有効化されます（BotFather で opt-out 可能）。

アップグレードチェックリスト

トラフィックを 10.2 のボットに切り替える前に、以下を進めてください。

番号作業重要な理由
1Bot API ライブラリを 10.2 対応版に固定（例：.NET の Telegram.BotAPI 10.2.0）型なしや古いクライアントは新フィールドを無視し、知らぬ間に劣化したメッセージを送る
2すべての sendRichMessage / InputRichMessage 構築を棚卸し新しい media と blocks により rich message の組み立て方が変わる
3メッセージハンドラに community_chat_added / community_chat_removed を追加未知のメッセージ型は default 分岐に落ちて失われる
4新しい ephemeral 編集／削除メソッドを採用するか判断再送なしで個別返信を修正できるようになる
5chat メタデータに ChatFullInfo の community を保存後で Community のトポロジーを推論するために必要
62026 年 7 月 20 日より前に Mini App の origin 処理をテストこの日からクロスオリジン呼び出しが遮断され始める
7inbound の正規化は単一の webhook に維持Rich block は送信専用で、inbound は引き続きプレーンテキスト

inbound チームにとって 10.2 が変えないこと

最も重要な「変化しない点」：ユーザーからの inbound メッセージは引き続き通常テキストで届きます。 ユーザーが Telegram のチャットに入力しても、あなたの受け取り側で RichMessage オブジェクトは生成されません。Rich Messages はボットが送るための機能です。これは Bot API 10.1 の分析 と同じ結論です。inbound の課題は rich block の解析ではなく、プラットフォーム横断のフォーマット正規化にあります。

つまり、メッセージの受信と振り分けが目的のチームは、10.2 のために inbound パーサーを書き直す必要はありません。今回のアップグレードが対象にするのは、ボットが送り返すものです。

UnifyPort の位置づけ

UnifyPort は inbound の Telegram メッセージ（WhatsApp・LINE・X・Zalo・TikTok とともに）を、単一の正規化された message.received イベントストリームとして届けます。そのため 10.2 アップグレードの inbound 側（ユーザーメッセージの受信、HMAC-SHA256 署名の検証、会話ごとのルーティング）は、Bot API のバージョンに関わらず変わります。

webhook のイベントカタログは安定しています。message.received、message.updated、message.deleted、message.read、message.reaction、さらに会話とアカウントのライフサイクルイベントがあります。各配信には X-Device-Event-Id、X-Device-Delivery-Id、X-Device-Timestamp、そして endpoint に signing_secret が設定されていれば hex エンコードの X-Device-Signature（"<タイムスタンプ>" + "." + "<生の body>" の HMAC-SHA256）が付きます。生の body で検証し、JSON を解析し、event.type で分岐させます。詳しい検証手順は webhook 配信と署名のガイド にあります。

アップグレードの目的が純粋にプラットフォーム横断の inbound 信頼性であれば、公式 Bot API に触れる必要はありません。同時に独自の Telegram ボットコードから rich や ephemeral の返信を送りたい場合に限り、10.2 の変更が関わります。UnifyPort の Telegram 認可 が、アカウント接続に必要な api_id / api_hash / 電話番号のフローを説明しています。

制限とトレードオフ

  • Rich Messages には対応クライアントが必要です。 非常に古い Telegram クライアントでは rich block が描画されないことがあり、プレーンテキストへのフォールバックが必要です。
  • Ephemeral メッセージはグループ管理者権限が必要で、1 ユーザーにしか届きません。ブロードキャスト用途ではありません。
  • Communities は新機能で進化中です。 今日の時点で Community 単位のメッセージ集約が存在すると仮定しないでください。chat ID ごとにルーティングし、トポロジーは届いた都度保存します。
  • 公式 Bot API は依然として単一プラットフォームです。 チームが WhatsApp・LINE・X の inbound も扱うなら、10.2 の採用は Telegram 側しか解決しません。クロスプラットフォームの inbound 問題は別途扱う必要があります。

よくある質問

Bot API 10.2 はいつ公開されましたか？

Telegram は 2026 年 7 月 14 日 に Bot API 10.2 を公開しました。公式 changelog（core.telegram.org/bots/api-changelog）に基づきます。主な追加は Rich Message のメディアとブロックビルダー、完全な ephemeral 編集／削除メソッド群、そして Communities です。

すぐにアップグレードしなければなりませんか？

受信機能を強制するアップグレード期限はありません。時限があるのは 2026 年 7 月 20 日 からの Mini App の origin 強制チェックのみです。Mini App を運用している場合は、この日より前にクロスオリジン挙動をテストしてください。

10.2 以降、inbound のメッセージ形式は変わりますか？

変わりません。Rich Messages はボットの送信専用機能です。ユーザーからの inbound は引き続きプレーンテキストや markdown で届き、inbound パーサーが rich block に対応する必要はありません。

Communities はグループチャットと同じですか？

違います。Community は複数の supergroup・channel・bot を束ねたものです。メッセージは元の chat に属したままで、chat ID ごとにルーティングと保存を行います。新設の community_chat_added と community_chat_removed のメッセージ型でトポロジー変更を追跡します。

UnifyPort は Telegram Community のライフサイクルイベントを受信できますか？

UnifyPort は Telegram の inbound を、統一 webhook 上の正規化された message.* およびライフサイクルイベントとして届けます。Community 固有のトポロジーイベントは、Communities イベントガイド の説明と同じ扱いにします。service-message のフィールドを保持し、getChat で突き合わせます。

次のステップ

  • webhook イベントカタログを確認し、inbound ハンドラが標準の message.* イベントを網羅しているか確かめてください。provider message support リファレンス を参照してください。
  • 初めて Telegram アカウントを接続する場合は、Quickstart が最初のメッセージ送受信までを案内します。

出典

  • Telegram Bot API changelog（公式）：https://core.telegram.org/bots/api-changelog — Bot API 10.2、2026-07-14。確認日 2026-07-30。
  • Telegram Bot API リファレンス（公式）：https://core.telegram.org/bots/api。確認日 2026-07-30。