Telegram Bot API 10.2 移行ガイド：リッチメッセージ、短命メッセージの編集、コミュニティ

Telegram Bot API 10.2 は小規模なバージョンアップに見えますが、実際には運用中の bot の複数の部分に同時に影響を与えます…

Dev.to · Jul 30, 2026

Telegram Bot API 10.2 Migration Guide: Rich Messages, Ephemeral Edits, and Communities

Telegram Bot API 10.2 は小規模なバージョンアップに見えますが、実際には運用中の bot の複数の部分に同時に影響を与えます：

リッチメッセージに型付きブロックと埋め込みメディアが追加
短命メッセージに完全な編集・削除ライフサイクルが追加
コミュニティに新しいトポロジーイベントとメタデータが導入
Mini App に厳格なオリジン保護が適用

Telegram は 2026 年 7 月 14 日に Bot API 10.2 をリリースしました。最も安全なアップグレード方法は、すべての新機能を即座に有効化しないことです。まずデータモデルとイベントディスパッチャーを更新し、各送信機能をフィーチャーフラグの後ろでテストしてください。

本ガイドでは公式 Bot API 10.2 変更履歴を実装チェックリストに変換しています。

影響マップから始める

コードを変更する前に、アップグレードを 4 つの領域に分けます。

領域	主な変更	主なリスク
リッチメッセージ	`media`、`blocks`、新しい `InputRichBlock*` 型	無効なペイロードまたは SDK のシリアライズ不完全
短命メッセージ	送信・返信・編集・削除のライフサイクル	ユーザー固有のメッセージ識別子の喪失
コミュニティ	新しいライフサイクルフィールドと `ChatFullInfo.community`	デフォルトハンドラーでのトポロジーイベントの破棄
Mini App	クロスオリジン呼び出しの保護強化	以前動作していたクロスオリジン呼び出しが拒否される

同じデプロイメントですべての機能を有効化する必要はありません。

合理的なロールアウト順序は以下の通りです：

ライブラリと型のアップグレード
新フィールドの受け入れと保存
ディスパッチャーカバレッジの追加
回帰テストの実行
送信機能の個別有効化

1. 互換性のある Bot API ライブラリを固定する

利用している Telegram ライブラリが Bot API 10.2 対応版をリリースしているか確認してください。

本番環境を更新する前に、以下を確認します：

生成された API 型
オプションフィールドのシリアライズ
メソッド名とパラメータのキャメルケース
Webhook 更新型
リトライとエラー処理
未知のメッセージフィールドへの対応

パッケージのアップグレードが自動的に新機能を有効化するとは考えないでください。一部のライブラリはすべてのメソッドを完全にサポートする前に新しい型を公開する場合があります。

選択したバージョンを固定し、オープンエンドの依存関係範囲は使用しないでください：

{
  "dependencies": {
    "your-telegram-library": "PINNED_COMPATIBLE_VERSION"
  }
}

フルスクリーンモードに入るフルスクリーンモードを退出

ブランチでアップグレードを実行し、ロールバック用に以前の依存関係バージョンも保持しておきます。

2. リッチメッセージの構築を監査する

Bot API 10.2 で追加されたもの：

InputRichMessageMedia
InputMediaVoiceNote
media on InputRichMessage
blocks on InputRichMessage
完全な InputRichBlock* ビルダー群

Bot API リファレンスによると、InputRichMessage は以下のいずれか 1 つのコンテンツ表現を使用しなければなりません：

html
markdown
blocks

ペイロードを動的に生成する場合、API 呼び出し前にこのルールを検証してください。

function validateRichMessage(input: {
  html?: string;
  markdown?: string;
  blocks?: unknown[];
  media?: unknown[];
}) {
  const representations = [
    input.html,
    input.markdown,
    input.blocks,
  ].filter((value) => value !== undefined);

  if (representations.length !== 1) {
    throw new Error(
      "A rich message must contain exactly one of html, markdown, or blocks",
    );
  }
}

フルスクリーンモードに入るフルスクリーンモードを退出

新しい media フィールドは、HTML または Markdown に埋め込まれたメディア参照に使用されます。例：

tg://photo?id=product_photo

フルスクリーンモードに入るフルスクリーンモードを退出

メディアを有効化する前に以下を確認してください：

メディア識別子がペイロード内で一意である
参照されたメディアが実際に media 配列に存在する
bot がそのメディアタイプを送信する権限を持っている
プレーンテキストのフォールバックが利用可能である
SDK がシリアライズ時にすべての新フィールドを保持する

依存関係のアップグレード時に既存の Markdown ビルダーをブロックビルダーに暗黙的に変換しないでください。これは別個の機能変更として扱ってください。

3. 短命メッセージの識別情報を保持する

Bot API 10.2 は以下のメソッドにより短命メッセージのライフサイクルを完成させました：

editEphemeralMessageText
editEphemeralMessageMedia
editEphemeralMessageCaption
editEphemeralMessageReplyMarkup
deleteEphemeralMessage

また Message に receiver_user と ephemeral_message_id が追加されました。

通常のメッセージ ID だけでは短命メッセージを管理できません。完全なルーティング識別子を保存してください：

type EphemeralMessageReference = {
  chatId: string;
  receiverUserId: number;
  ephemeralMessageId: number;
};

フルスクリーンモードに入るフルスクリーンモードを退出

ライブラリの呼び出しは以下のように記述できます（正確なメソッド名は SDK により異なります）：

await bot.editEphemeralMessageText({
  chat_id: chatId,
  receiver_user_id: receiverUserId,
  ephemeral_message_id: ephemeralMessageId,
  text: "Your request has been updated.",
});

フルスクリーンモードに入るフルスクリーンモードを退出

返信の構築も見直してください。Bot API 10.2 では ReplyParameters.message_id が ephemeral_message_id 存在時にオプショナルになりました。

実装では以下をテストしてください：

意図したユーザーに送信
テキストの編集
メディアまたはキャプションの編集
リプライマークアップの更新
メッセージの削除
不正なユーザーコンテキストからの編集の拒否
期限切れまたは不明な識別子の処理
リトライによる重複返信の防止

短命メッセージはユーザー固有です。グループブロードキャスト機構として扱わないでください。

4. コミュニティイベントをディスパッチャーに追加する

コミュニティは共有トピックまたはオーディエンスを中心にスーパーグループ、チャンネル、ボットを結び付けます。

Bot API 10.2 で導入されたもの：

Community
CommunityChatAdded
CommunityChatRemoved
message.community_chat_added
message.community_chat_removed
ChatFullInfo.community

message.text のみを確認するハンドラーは、これらのサービスメッセージを暗黙的に破棄する可能性があります。

明示的な分岐を追加してください：

function handleMessage(message: TelegramMessage) {
  if (message.community_chat_added) {
    recordCommunityChatAdded(message);
    return;
  }

  if (message.community_chat_removed) {
    recordCommunityChatRemoved(message);
    return;
  }

  if (message.text) {
    handleTextMessage(message);
    return;
  }

  handleUnknownMessageType(message);
}

フルスクリーンモードに入るフルスクリーンモードを退出

コミュニティ ID を元のチャット ID の代わりに使用しないでください。

コミュニティはトポロジーを記述します。メッセージは依然として元のチャット識別子に基づいて保存・ルーティングする必要があります。

実用的なメタデータモデルでは両方を保持できます：

type CommunityChatRelation = {
  communityId: string;
  chatId: string;
  relationStatus: "active" | "removed";
  observedAt: string;
};

フルスクリーンモードに入るフルスクリーンモードを退出

トポロジーが変更された場合は：

ライフサイクルイベントを永続化
リレーション状態を更新
getChat で現在の情報を再調整
監査レコードを保持
元のチャット ID でメッセージのルーティングを継続

5. 追加の更新型を処理する

Bot API 10.2 は BotSubscriptionUpdated と Update の subscription フィールドも追加しました。

bot が現在決済サブスクリプションを使用していなくても、Webhook デコーダーがこのフィールドの存在だけで更新を拒否しないようにしてください。

安全なパターンは：

既知のトップレベルフィールドをパース
未知のフィールドは可能な限り保持
機密ペイロードなしでイベントカテゴリをログ
未対応の更新を観測可能なフォールバックにルーティング
Webhook リクエスト全体の失敗を避ける

未知の更新に対して毎回非成功レスポンスを返すと不要なリトライが発生します。

6. Mini App のオリジンを再確認する

Telegram は BotFather でオプトアウトしない限り、2026 年 7 月 20 日に Mini App のオリジン保護を自動的に強化しました。

以下を監査してください：

設定された Mini App ドメイン
リダイレクト先
埋め込み認証ページ
決済またはサポートページ
ナビゲーション後の呼び出し
Mini App 内で開かれるサードパーティコンテンツ
開発・ステージングドメイン

どのページが呼び出しを開始したかを理解せずに保護を広範に無効化してオリジンエラーを解決しないでください。

本番ドメインと各許可された非本番環境を個別にテストしてください。

7. 不要なインバウンド書き換えを避ける

新しい InputRichMessage ビルダーは主にアウトバウンドパスに影響します。

すべての通常の受信ユーザーメッセージを突然リッチブロックのツリーとして解析する必要があるという意味ではありません。

インバウンド作業は以下に集中してください：

新しいコミュニティサービスメッセージフィールドの認識
subscription 更新の受け入れ
新しいオプションフィールドの保持
観測可能な未知イベントフォールバックの保持
既存のテキスト・メディア・コールバック処理の維持

これは互換性更新であり、動作しているインバウンド正規化パイプラインを置き換える理由ではありません。

8. 個別のフィーチャーフラグの後ろでデプロイする

単一のグローバル「Bot API 10.2」スイッチではなく、独立したフラグを使用してください。

const telegramFeatures = {
  richMessageBlocks: false,
  richMessageMedia: false,
  ephemeralEdits: false,
  communityTopology: true,
};

フルスクリーンモードに入るフルスクリーンモードを退出

これにより、新しいアウトバウンドフォーマットを遅延させつつ、コミュニティイベントをすぐに受け入れることができます。

安全なロールアウトは以下のようになります：

Upgrade dependency
        ↓
Accept new webhook fields
        ↓
Deploy with outbound flags disabled
        ↓
Verify normal inbound traffic
        ↓
Enable one outbound feature internally
        ↓
Monitor errors and payloads
        ↓
Expand gradually

フルスクリーンモードに入るフルスクリーンモードを退出

少なくとも以下を監視してください：

Telegram API エラーコード
シリアライズ失敗
未知の更新数
コミュニティトポロジーの変更
短命メッセージの編集・削除失敗
リッチメッセージのフォールバック使用
Webhook リトライ量

9. ロールバックパスを構築する

本番ロールアウト前に以下を記録してください：

以前のライブラリバージョン
新しいデータベースフィールド
フィーチャーフラグのデフォルト
ペイロード形式の差異
可逆・不可逆マイグレーション
ロールバック責任者
監視閾値

新フィールドがオプショナルである場合は、追加型のデータベース変更を優先してください。ロールアウト中に作成されたレコードを以前のアプリケーションバージョンが読み取れなくなるような変更は行わないでください。

ロールバックでは、新しい送信を無効化しつつ、既に配信済みの Webhook フィールドは引き続き受け入れるようにしてください。

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

[ ] Bot API ライブラリバージョンが固定されている
[ ] 新しい SDK 型とシリアライズが検査済み
[ ] 既存のインバウンド回帰テストがパス
[ ] リッチメッセージ表現がちょうど 1 つに強制されている
[ ] リッチメッセージのメディア参照が検証済み
[ ] プレーンテキストフォールバックが利用可能
[ ] 短命メッセージ識別子が永続化されている
[ ] 短命メッセージの編集・削除失敗パスがテスト済み
[ ] コミュニティライフサイクルイベントに明示的なハンドラ分岐がある
[ ] コミュニティトポロジーがチャットルーティングとは別に保存されている
[ ] subscription 更新が Webhook デコードを破壊しない
[ ] Mini App の本番・ステージングオリジンが確認済み
[ ] アウトバウンド機能が個別のフラグを使用している
[ ] 未知の更新が観測可能である
[ ] 依存関係と機能のロールバック手順が文書化されている

Bot API 10.2 は、1 つの大規模機能リリースではなく、いくつかの小さなマイグレーションとして扱うことで管理可能です。

まず互換性レイヤーを更新してください。基盤となるフィールド、ルーティングルール、ロールバックパスが準備できてから、リッチメッセージ、短命メッセージの編集、コミュニティ対応動作を有効化してください。

公式リファレンス

Originally published on UnifyPort.

This article was prepared with AI assistance for language and structure, then technically reviewed and verified by the author.

Read the original source Next news

#Backend

Telegram Bot API 10.2 移行ガイド：リッチメッセージ、短命メッセージの編集、コミュニティ

影響マップから始める

1. 互換性のある Bot API ライブラリを固定する

2. リッチメッセージの構築を監査する

3. 短命メッセージの識別情報を保持する

4. コミュニティイベントをディスパッチャーに追加する

5. 追加の更新型を処理する

6. Mini App のオリジンを再確認する

7. 不要なインバウンド書き換えを避ける

8. 個別のフィーチャーフラグの後ろでデプロイする

9. ロールバックパスを構築する

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

公式リファレンス

0 Comments