gramio

GramIO

GramIO は、TypeScript 向けのモダンで型安全な Telegram Bot API フレームワークです。Node.js、Bun、Deno で動作し、Bot API を完全に網羅するとともに、合成可能なプラグインシステムと、TypeScript の一級サポートを備えています。

このスキルを使う場面

• Telegram ボットを作成または変更するとき
• ボットのコマンド、コールバック、インラインクエリ、リアクションを設定するとき
• キーボード（返信、インライン、削除、強制返信）を作成するとき
• エンティティ（太字、斜体、コード、リンク、メンション）を使ってメッセージをフォーマットするとき
• ファイルやメディアをアップロードまたはダウンロードするとき
• ユーザーセッションや複数ステップの会話フロー（シーン）を管理するとき
• カスタムプラグインを作成するとき
• Webhook またはロングポーリングを設定するとき
• Telegram Stars で支払いを処理するとき
• レート制限に対応しながらメッセージを一斉送信するとき
• バックエンド認証を備えた Telegram Mini Apps（TMA）を構築するとき
• Docker でボットをコンテナ化するとき
• カスタム Bot API ラッパーにスタンドアロンの @gramio/types を使用するとき
• カスタムプラグインを作成して公開するとき
• puregram、grammY、Telegraf、node-telegram-bot-api から GramIO にボットを移行するとき

クイックスタート

npm create gramio bot-name
cd bot-name
npm run dev

基本パターン

import { Bot } from "gramio";

const bot = new Bot(process.env.BOT_TOKEN as string)
    .command("start", (context) => context.send("Hello!"))
    .onStart(({ info }) => console.log(`@${info.username} started`))
    .onError(({ context, kind, error }) => console.error(`[${kind}]`, error));

bot.start();

イントロスペクションツール

このスキルには、ディスク上のインストール済み@gramio/* および gramio パッケージを解析する Node.js スクリプトが 4 つ含まれています。URL の取得や telegram-api-index の読み込みよりも、これらを優先してください。各呼び出しでは、ドキュメントの大量表示ではなく、対象を絞ったバージョンに正確なシグネチャが返されます。

ユーザーのプロジェクトルート（node_modules/ がある場所）から実行してください。ツールの出力先は stdout、エラーと自動修正のヒントの出力先は stderr です。

ツール	使用する場面
tools/get-bot-api-method.mjs <name>	Bot API メソッドのシグネチャが必要なときに使います（例：sendMessage、createChatInviteLink）。@gramio/types から JSDoc とパラメーター／戻り値の型を返します。--list ですべてのメソッドを表示し、--search <term> で名前や説明を絞り込めます。
tools/get-bot-api-type.mjs <name>	Telegram の型定義が必要なときに使います（例：Message、ChatInviteLink）。短い名前（Message）と完全な名前（TelegramMessage）のどちらも受け付けます。同じ --list／--search フラグを使用できます。
tools/get-context-getter.mjs <ClassName>	コンテキストが公開するゲッター／メソッド（MessageContext、CallbackQueryContext、User、Chat）を確認するときに使います。--deep を追加すると、ミックスインと統合されたインターフェースを再帰的に取得します。--search <name> では、指定したゲッター／メソッドを公開するすべてのクラスを検索できます（例：firstName は User、Chat、Contact、SharedUser にあります）。
tools/get-plugin.mjs <name>	プラグインのエントリー関数のシグネチャと、コンテキストに追加される内容（例：session、scenes、i18n）が必要なときに使います。--list ですべてのインストール済み @gramio/* パッケージを表示します。

node tools/get-bot-api-method.mjs sendMessage
node tools/get-bot-api-type.mjs InlineKeyboardMarkup
node tools/get-context-getter.mjs MessageContext --deep
node tools/get-context-getter.mjs --search chatId
node tools/get-plugin.mjs session

スクリプトはあいまい一致に対応しており（sendMesage → sendMessage）、一致しない場合は代替候補を提示します。関連パッケージがインストールされている必要があります。インストールされていない場合は、正確な npm install のヒントが表示されます。

重要な概念

1. コールバックのルーティング — コールバックデータを手動で解析しないでください。 CallbackData.pack() が生成するのは、6 文字のハッシュプレフィックス（スキーマ名の sha1-base64url）とシリアライズされたペイロードであり、"nav:" のようなリテラルのプレフィックスではありません。ctx.data.startsWith("nav:") のようなチェックは、実行時に必ず失敗します。データの形状に応じて、次の 4 つのパターンから 1 つを使ってください。

   // Fixed string → exact string match
   bot.callbackQuery("refresh", (ctx) => ctx.answer("Refreshed"));
   
   // Pattern / variable slug → RegExp with capture groups
   bot.callbackQuery(/^user_(\d+)$/, (ctx) => {
       const [, id] = ctx.match!;
       ctx.answer(`User ${id}`);
   });
   
   // Structured data → CallbackData schema (preferred for multi-field payloads)
   import { CallbackData } from "gramio";
   const nav = new CallbackData("nav").enum("to", ["home", "history", "admin"]);
   bot.callbackQuery(nav, (ctx) => {
       ctx.queryData.to; // "home" | "history" | "admin" — fully typed
   });
   
   // Stale-safe unpack (when inline keyboard may outlive a schema change)
   const result = nav.safeUnpack(ctx.data!);
   if (!result.success) return ctx.answer("Button expired");
   result.data.to; // typed
   

   // ❌ NEVER — hashed prefix means string compare won't match,
   //    and you lose full type safety.
   if (ctx.data?.startsWith("nav:")) {
       const [, to] = ctx.data.slice(4).split(":");
       // ...
   }
   

   プラグイン間でハンドラーが重複した場合の動作については、callback-data と middleware-routing を参照してください。

2. メソッドチェーン — ハンドラー、フック、プラグインは .command()、.on()、.extend() などで連結します。順序が重要です。同じ更新に一致するハンドラーが 2 つある場合、next() を呼び出さない限り、最初に登録されたハンドラーが実行されます。middleware-routing を参照してください。

3. 型安全なコンテキスト — コンテキストは更新タイプに基づいて自動的に型付けされます。汎用ハンドラーで型を絞り込むには、context.is("message") を使用します。.derive()／.decorate()／.extend(plugin) の後は、新しいフィールドが推論されたコンテキスト型に自動的に追加されます。ctx as unknown as { myField } のようなキャストは絶対にしないでください。ボットのコンテキスト型をエクスポートして再利用します（context →「derive 後のコンテキスト型」を参照）。

4. コンテキストのゲッター — 常に camelCase を使用し、ctx.payload や ctx.update.* には触れないでください — Telegram のすべてのフィールドは camelCase のゲッター（ctx.from、ctx.firstName、ctx.chatId、ctx.messageId、ctx.text、ctx.data、ctx.queryData）として公開されます。ctx.payload と ctx.update はどちらも内部の生の snake_case オブジェクトです。ハンドラーのコードでは使用しないでください。

5. プラグインシステム — new Plugin("name").derive(() => ({ ... })) を使うと、型付きのプロパティがコンテキストに追加されます。bot.extend(plugin) で登録します。

6. フックのライフサイクル — onStart →（onError を伴う更新）→ onStop。API 呼び出し：preRequest → call → onResponse/onResponseError。

7. エラーの抑制 — bot.api.method({ suppress: true }) は、エラーをスローせずに返します。

8. 遅延プラグイン — 非同期プラグイン（await を付けない場合）は bot.start() で読み込まれます。すぐに読み込むには await を使用します。

9. Derive と Decorate の違い — .derive() は更新ごとに実行されます（値を計算します）。.decorate() は静的な値を一度だけ注入します。

10. 書式設定 — 重要な 4 つのルール（メッセージ本文を書く前に書式設定を読んでください）：

    • parse_mode は絶対に使用しないでください — format は HTML／Markdown 文字列ではなく、MessageEntity 配列を生成します。parse_mode: "HTML" や "MarkdownV2" を追加すると、メッセージが壊れます。GramIO はエンティティを自動的に渡します。
    • 書式設定された値の配列にネイティブの .join() は絶対に使用しないでください — 各 Formattable に対して .toString() が呼び出され、書式がすべて暗黙のうちに失われます。必ず join ヘルパーを使用してください：join(items, (x) => bold(x), "\n")。
    • 書式設定されたコンテンツを合成または再利用する場合は、**必ず format\`で囲んでください** — プレーンなテンプレートリテラル（``${boldx}``）にFormattableを埋め込むと、すべてのエンティティが失われます。代わりにformat`${bold`x`}`` を使用してください。
    • FormattableString に .toString() を絶対に呼び出さないでください — send、editMessageText、editMessageCaption などの text:／caption: パラメーターに直接渡してください。.toString() を呼び出すと、すべてのエンティティが失われます。編集後にマジックリンクや書式設定されたエンティティが「機能しなくなる」最大の原因です。

11. シーン — ステップのセマンティクスと更新タイプによるフィルタリング — context.scene.step.go(N) と context.scene.step.next() は、シーンのミドルウェアチェーンを直ちに実行します。ただし、各 .step(updateName, handler) は context.is(updateName) でフィルタリングします。現在のコンテキストが callback_query で、次のステップが .step("message", …) の場合、そのステップは実行されません。UI を直接送信してから return step.next() を実行するか、.step(["message", "callback_query"], …) を使用するか、onEnter／現在のステップのコールバックハンドラーでプロンプトを表示してください。単一の値を検証済み入力として受け取る場合は、.ask("field", zodSchema, "prompt") を使用してください。シーンを参照してください。

12. InlineQueryResult ビルダー — インライン結果には InlineQueryResult.article(id, title, InputMessageContent.text(...)) などのビルダーメソッドを使用してください。bot.inlineQuery(/regex/, handler) でインラインクエリをルーティングします。トリガーを参照してください。

13. 画面の構成 — インラインの ctx.send / ctx.editText より @gramio/views を優先してください — 画面が数個を超えるボットでは、@gramio/views プラグインを使って再利用可能なビューのテンプレートを定義し、context.render(view, params) でレンダリングしてください。更新の種類に応じて送信と編集を自動判定し、テキスト、キーボード、メディア（{{param}} / {{$global}} の補間やアダプターファクトリーによる i18n に対応した JSON 駆動のテンプレートを含む）を一元管理します。また、ctx.send(...) と ctx.editText(...) の呼び出し箇所にメッセージ本文を重複させるという、よくある失敗を防ぎます。シンプルなレンダリング関数のパターンは、メニューだけの単純なボット（画面が2〜3個、メディアなし、i18n なし）には適していますが、それ以上のものには @gramio/views を使ってください。@gramio/views は現在開発中のため（ヘルパーやアダプターの詳細は変更される可能性があります）、基本的な構成（initViewsBuilder、.render(fn)、context.render(...)）は安定しており、GramIO でのビュー構成に推奨される方法です。views を参照してください。

14. @gramio/prompt はメモリー上のみで動作し、永続化されません。複数ステップのフロー、接続フロー、オンボーディングフローには Scenes と .ask() を使ってください。 context.prompt(...) / context.wait(...) が返す Promise は、現在の Node.js プロセス内に存在します。プロセスが再起動した時点（デプロイ、クラッシュ、コンテナーの再スケジュール、dyno の再起動）で Promise は失われます。ユーザーの次のメッセージは回答として扱われず、エラーも発生せず、ボットはユーザーがどの段階にいたかをひそかに「忘れます」。これは OAuth 接続フロー（Spotify/Last.fm など）、オンボーディングウィザード、支払いの受付、デプロイ後も維持する必要がある一連の質問にとって致命的です。一方、Scenes は設定済みのストレージ（Redis / Cloudflare / カスタムストレージ）にステップのインデックスと収集した回答を保存し、次の更新時に復元します。ルール： @gramio/prompt を使用できるのは、再起動時にフローが失われても問題のない、プロセス内で完結する単一の質問のプロンプトに限られます（使い捨ての確認やデバッグ用ヘルパーなど）。重要な一連の質問や、「質問 → 検証 → 再質問」を行う接続フローはすべて、.ask("field", zodSchema, "prompt message") を使う Scene にまとめてください。.ask() は、prompt と同じ firstTime による分岐や検証の再試行に関する定型コードをなくし、さらに状態を永続化します。複数ステップのフローで、Scenes より簡単な代替手段として @gramio/prompt を推奨しないでください。この推奨の落とし穴を防ぐことが、この概念の目的です。scenes と prompt を参照してください。

15. サブエージェントへの委任 — スキルはサブエージェントのセッション内では自動的に有効になりません。ボットのコードを書くサブエージェントを起動する際は、関連するリファレンスファイルのパス（例：skills/references/callback-data.md、skills/plugins/scenes.md、skills/references/formatting.md、skills/references/middleware-routing.md）をエージェントのプロンプトに明示的に渡すか、重要なルールをインラインで含めてください。

16. 例ではどこにも any を使わないでください — skills/ 以下のファイル（例、Markdown のコードブロック、プラグインのドキュメント）では、ctx: any、as any、<any>、暗黙の any パラメーターを決して書かないでください。スキルの例は、AI がユーザーのボットにそのままコピーするテンプレートです。ここにある any は、下流のすべてのボットに広がります。ContextType<typeof bot, "update_name">、CallbackQueryShorthandContext<typeof bot, typeof schema> から適切な型を導出するか、BotContext = typeof bot['_']['context'] というエイリアスをエクスポートしてください。システムとの境界で値の型が本当に不明な場合は、unknown を使って型を絞り込んでください。「避けるべきこと」を示すスニペットであっても例外はありません。広範な any の代わりに、該当する行でコメントとともに @ts-expect-error を使ってください。

17. ボタン優先の UX — ユーザーは入力するのではなく、タップします。 ナビゲーションにはスラッシュコマンドではなく、インラインキーボードを使います。/start は短いヒーロー（太字のタイトル＋引用ブロック形式の説明）と主要なアクションのインラインキーボードを表示します。/help、/settings、/delete を並べた長文にはしません。ネストされたメニューでは、タイトルにパンくずリスト（⚙️ Settings · home › settings）を表示し、ホーム以外の画面には ◀ Back ボタンを、2 階層より深い場所には 🏠 Home ボタンを設置します。ナビゲーションのクリックでは、メッセージを新規送信せず、現在のメッセージを編集します（ctx.editText）。新規送信は結果や通知などのイベント用であり、ナビゲーションには使いません。切り替えボタンは状態をラベルで示します（✅ Notifications / ⬜ Notifications）。1 つのハンドラーでセッションフィールドを切り替え、画面を再描画します。破壊的な操作では必ず確認画面を表示し、安全なデフォルトの選択肢を左側に配置します。すべてのコールバックハンドラーでは、スピナーをすぐに止めるため、最初に ctx.answer() を呼び出します。ナビゲーションでは空の応答で問題ありません。トースト表示には短いテキストを使い、{ show_alert: true } はユーザーが確認する必要のあるエラーに限って使います。コマンドは見つけやすくするために用意し（Telegram のメニューボタンに表示されるよう setMyCommands で登録します）、主要な UI としては使いません。詳しい手順は ux-patterns を、ヒーロー形式の /start、ネストされたメニュー、切り替えボタン、破壊的な操作の確認を扱った実例は examples/ux-menu.ts を参照してください。

18. スキルを編集したら、完了前に必ず bun run check:skills を実行してください — skills/**/*.ts または skills/**/*.md 内の TypeScript コードブロックを変更した場合は、インストール済みの現在の gramio バージョンに対して型チェックを通す必要があります。check:skills スクリプトは、厳格モードで skills/examples/*.ts に対して tsc --noEmit を実行します。エラーが報告された場合は修正してください。そのままリリースしてはいけません。既存のサンプルが gramio の API の進化によって動作しなくなった場合は、現在の API に合わせてサンプルを更新してください（現在のシグネチャは node_modules/gramio/dist/index.d.ts と node_modules/@gramio/*/dist/index.d.ts で確認してください）。

19. リッチメッセージは独立した送信手段です — Markdown 用には rich / markdownTable を、ネイティブの構造化ブロックには blocks / table を、リッチ JSX には @gramio/jsx/rich を使います。リッチ値は sendMessage ではなく sendRichMessage にルーティングされます。streamRichMessage は Markdown のチャンクを基準にしています。ネイティブのブロックは ctx.send / ctx.sendRichMessage で直接送信してください。アップロードは rich_message.blocks / .media 内で再帰的に処理されますが、sendRichMessageDraft での直接アップロードは禁止されています。ユーザーによるキャンセルは bot.on("stopped_message_generation", ...) で処理してください。rich-messages を参照してください。

公式プラグイン

プラグイン	パッケージ	用途
セッション	@gramio/session	ユーザーごとのデータを永続的に保存
シーン	@gramio/scenes	複数ステップの会話フロー
オンボーディング	@gramio/onboarding	装飾専用 — 宣言型のチュートリアル／機能紹介。複数フローの同時実行、拒否ラダー、スコープを考慮したレンダリングに対応。フォーム／ウィザード用ツールではありません — その用途には Scenes を使用してください
I18n	@gramio/i18n	国際化（TS ネイティブまたは Fluent）
自動読み込み	@gramio/autoload	ファイルベースのハンドラー読み込み
プロンプト	@gramio/prompt	1つの質問をするプロンプト — メモリ内のみで、永続化されません。再起動後も保持する必要がある場合は、Scenes の .ask() を使用してください
ビュー	@gramio/views	画面構成に推奨 — 再利用可能なテンプレート（プログラムによる作成＋JSON）、自動送信／編集、キーボード、メディア、i18n
JSX	@gramio/jsx	書式設定とキーボードのための JSX 構文（React は不要）
ページネーション	@gramio/pagination	流暢なビルダーで作成するページ分割されたインラインキーボードメニュー
自動再試行	@gramio/auto-retry	429 レート制限時に再試行
メディアキャッシュ	@gramio/media-cache	file_id をキャッシュ
メディアグループ	@gramio/media-group	アルバムメッセージを処理
分割	@gramio/split	長いメッセージを分割
コールバッククエリの自動応答	@gramio/auto-answer-callback-query	コールバックに自動応答
PostHog	@gramio/posthog	分析＋機能フラグ
OpenTelemetry	@gramio/opentelemetry	分散トレーシングとスパン
Sentry	@gramio/sentry	エラー追跡＋パフォーマンス監視

Telegram Bot API リファレンスページ

GramIO のドキュメントには、Telegram Bot API のすべてのメソッドと型に対応する専用のリファレンスページがあります。

• メソッド：https://gramio.dev/telegram/methods/{methodName} — 例：sendMessage、createChatInviteLink、answerCallbackQuery
• 型：https://gramio.dev/telegram/types/{typeName} — 例：Message、ChatInviteLink、InlineKeyboard

各ページには、GramIO 用の TypeScript の例、パラメーターの詳細、原因と修正方法を記載したエラー一覧、ヒントと注意点、関連リンクが掲載されています。特定の Telegram API メソッドや型について質問された場合、対応するページを取得または参照することで、GramIO に特化した正確な使い方を案内できます。

LLM 向けのヒント： URL の末尾に .md を追加すると、GramIO のドキュメントページをクリーンな Markdown として取得できます。 https://gramio.dev/telegram/methods/sendMessage.md — HTML ではなく、クリーンな Markdown が表示されます。 API ページだけでなく、ドキュメントのすべてのセクションで利用できます。

これらのページはデフォルトではこのスキルに含まれていません — 特定のメソッド／型について質問された場合に、必要に応じて取得してください。

メソッドをすばやく検索するには — 事前作成されたインデックスを使用してください：telegram-api-index。Bot API の165以上のメソッドが、短い説明とともに1つのファイルにまとめられています。メソッド名を見つけたいときや、詳細ページを取得する前にメソッドの存在を確認したいときに読み込んでください。

参考資料

コア

トピック	説明	リファレンス
ボットの設定	コンストラクター、API オプション、プロキシ、テスト用 DC、デバッグ	bot-configuration
ボット API	メソッドの呼び出し、抑制、withRetries、型ヘルパー	bot-api
コンテキストと更新	derive、decorate、ミドルウェア、開始／停止、型の絞り込み	context
トリガー	command、hears、callbackQuery、inlineQuery、reaction	triggers
フィルター	型安全なコンテキストの絞り込み — フィルター専用の .on()、filters.* の述語、guard()	filters
ミドルウェアのルーティング	ハンドラーの優先順位、next()、重複する CallbackData、集中管理されたルーティング	middleware-routing
Scene ↔ Composer の継承	名前付き .as("scoped") コンポーザーを共有し、ボットレベルのハンドラーと Scene のステップ間で派生させます。循環インポートを避けるためにファイルを分割します	scene-composer-inheritance
フック	onStart、onStop、onError、preRequest、onResponse	hooks
更新とライフサイクル	start／stop オプション、グレースフルシャットダウン（SIGINT／SIGTERM）	updates
トラブルシューティング	症状 → 原因 → 解決策：409 conflict、書式の崩れ、スピナーの停止、オプトインが必要な更新の欠落、セッションなしのシーン、snake_case アクセス、await されていない MediaUpload	troubleshooting

機能

トピック	説明	リファレンス
キーボード	Keyboard、InlineKeyboard、レイアウトヘルパー、スタイル設定	keyboards
書式設定	エンティティヘルパー、join（ネイティブの .join() は使用しないでください！）、変数の組み合わせ、parse_mode なし	formatting
リッチメッセージ	Markdown／構造化ブロックのヘルパー、リッチ JSX、再帰的なアップロード、下書き、生成停止の更新	rich-messages
UX パターン	ボタン優先のナビゲーション、/start の構成、ネストされたメニュー、切り替え、破壊的操作の確認、空の状態、書式の階層、コマンドの発見	ux-patterns
ディープリンク	あらゆる t.me/<bot>?... リンクの種類 — ?start=、?startgroup=、?startchannel=、?startapp=、?startattach=、?game= — それぞれのリンク先となるハンドラー／コンテキストフィールド、ペイロードのエンコード規則、admin= 権限トークン、注意点	deep-links
ファイル	MediaUpload、MediaInput、ダウンロード、Bun.file()	files
CallbackData	型安全なコールバックデータスキーマ	callback-data
ストレージ	インメモリ、Redis、Cloudflare アダプター	storage
Telegram Stars	決済、請求書、サブスクリプション、インライン請求書、返金、テストモード	telegram-stars
型	@gramio/types、型ヘルパー、Proxy ラッパー、宣言マージ	types

インフラストラクチャ

トピック	説明	リファレンス
Webhook	フレームワーク統合、トンネリング、カスタムハンドラー	webhook
レート制限	withRetries、ブロードキャスト、キュー	rate-limits
Docker	Dockerfile、マルチステージビルド、Docker Compose	docker
ローカル Bot API サーバー	telegram-bot-api のセルフホスト、クラウドからローカルへの移行（logOut + api.baseURL）、2 GB のアップロード、トークン不要のファイルダウンロード	local-bot-api
tdlight (@gramio/tdlight)	userbot／ユーザーモード、追加メソッド（searchMessages/getChats/votePoll）、スケジューリング、プロキシ、追加のオブジェクトフィールド、メソッド名に関する落とし穴、Docker	tdlight
TMA	ミニアプリ、mkcert HTTPS、@gramio/init-data 認証	tma
テスト	イベント駆動型のボットテスト、ユーザーアクター、API モック	testing

移行

既存のボットを GramIO に移行する場合に読み込みます。

移行元	説明	リファレンス
grammY	Flavor ジェネリクス → derive/extend、名前付き API パラメーター、conversations → scenes、チェックリスト	migration-from-grammy
puregram	シンボルの対応表、API の比較、puregram → GramIO のリファクタリング用チェックリスト	migration-from-puregram
Telegraf	シンボルの対応表、コンテキストの型付け、Scenes/WizardScene、Webhook の違い、チェックリスト	migration-from-telegraf
node-telegram-bot-api	シンボルの対応表、ミドルウェアの概念、キーボードビルダー、セッション、チェックリスト	migration-from-ntba

gramio/@gramio/* のバージョンをまたいで既存の GramIO プロジェクトをアップグレードする場合（別のフレームワークから移行するのではなく）→ 単独の gramio-upgrade スキル（skills/gramio-upgrade/SKILL.md）を使用します。インストール済みのバージョンを検出し、バージョンごとの変更履歴（skills/gramio-upgrade/MIGRATIONS.md）から、現在のバージョンと対象バージョンの間にある破壊的変更、非推奨機能、新機能を確認して、修正を適用します。

プラグイン

プラグイン	説明	リファレンス
Session	ユーザーごとのデータ、Redis のサポート	session
Scenes	複数ステップのフロー、状態、ナビゲーション	scenes
Onboarding	複数フローの同時実行に対応した装飾的なチュートリアル — フォームには Scenes と組み合わせて使用	onboarding
I18n	TS ネイティブおよび Fluent による国際化	i18n
Autoload	ファイルベースのハンドラー検出	autoload
Prompt	送信して応答を待機 — インメモリのみで、再起動すると失われます。永続的な質問シーケンスには Scenes の .ask() を使用します	prompt
Views	推奨パターン — @gramio/views プラグイン（テンプレート、JSON、i18n、自動送信・編集）。単純なボットには通常の render-fn を代替として使用	views
JSX	書式設定とキーボードに JSX 構文を使用（React ランタイムは不要）	jsx
Pagination	流暢なページネーション対応のインラインキーボード（前へ／次へ／最初／最後、ページ情報）	pagination
OpenTelemetry	分散トレーシング、スパン、インストルメンテーション	opentelemetry
Sentry	エラートラッキング、パフォーマンスモニタリング	sentry
Others	自動リトライ、メディアキャッシュ、メディアグループ、分割、posthog	other
Plugin Development	カスタムプラグインの作成、derive/decorate/error、遅延読み込み	plugin-development

例

例	説明	ファイル
基本的なボット	コマンド、フック、エラー処理	basic.ts
キーボード	返信、インライン、列、条件分岐	keyboards.ts
UX メニュー	ヒーロー /start、パンくずリストと戻るボタン付きのネストされたメニュー、トグルボタン、破壊的操作の確認ステップ	ux-menu.ts
CallbackData	型安全なコールバックのスキーマ	callback-data.ts
フォーマット	エンティティの種類、結合ヘルパー、変数の構成、parse_mode のアンチパターン	formatting.ts
ファイルのアップロード	パス、URL、バッファー、メディアグループ	file-upload.ts
エラー処理	カスタムエラー、抑制、スコープ指定	error-handling.ts
Webhook	フレームワークとの統合	webhook.ts
セッション	カウンター、設定、Redis	session.ts
シーン	ステップ形式の登録フロー	scenes.ts
ウィザードシーン	コールバック駆動のシーン、コールバックとメッセージを組み合わせたステップ、グローバルな終了処理	wizard-scene.ts
シーンコンポーザーの継承	3 ファイルのパッケージ：名前付きのスコープ付きコンポーザー＋Scene.extend＋循環インポートを避けるファイル分割レイアウト	scene-composer-inheritance/
コールバックのルーティング	一元化されたルーター、機能間で共有するナビゲーション用 CallbackData	callback-routing.ts
Telegram Stars	支払い、請求書、返金	telegram-stars.ts
TMA	Elysia サーバー、init-data 認証、Webhook	tma.ts
Docker	グレースフルシャットダウン、Webhook／ポーリングの切り替え	docker.ts
テスト	ユーザーのシミュレーション、API のモック化、エラーのテスト	testing.ts
ディープリンク	/start ペイロードのルーティング（参照／注文／不透明なトークン／インラインモードへのリダイレクト）＋ ?startchannel／?startgroup リンクに対する my_chat_member による管理者権限の確認	deep-links.ts