Telegram Bot Builder

Bot API (v9.4) を使用した Telegram ボット構築の包括的なガイダンス。Node.js と Python 生態系の両方をカバーし、認証、メッセージング、キーボード、メディア処理、支払い、インラインモード、ウェブフック、デプロイメントの本番対応パターンを提供します。

このスキルの使用時期

以下の場合にこのスキルを使用してください：

• ゼロから新しい Telegram ボットを構築する
• Telegram メッセージングを既存アプリケーションに統合する
• ボット更新用のウェブフックまたはロングポーリングを設定する
• インラインキーボードとコールバッククエリを使用したインタラクティブメニューを作成する
• メディア（写真、ビデオ、ドキュメント、ステッカー）を処理する
• Telegram Payments または Telegram Stars を実装する
• インラインモード機能を構築する
• ボット経由でグループ、チャネル、またはフォーラムトピックを管理する
• ボットを本番環境にデプロイする (Docker、PM2、サーバーレス)

コア概念

認証

すべてのボットは @BotFather から取得した一意のトークンを持っています。トークン形式：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。

すべての API 呼び出しは以下に送信されます：https://api.telegram.org/bot<TOKEN>/METHOD_NAME

# .env ファイル
BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

トークンは環境変数に保存します。ソースコードにコミットしないでください。

更新の受け取り：ポーリングとウェブフック

ロングポーリング (getUpdates) - よりシンプル、HTTPS 不要、開発に最適：

// node-telegram-bot-api を使用した Node.js
const bot = new TelegramBot(process.env.BOT_TOKEN, { polling: true });

# python-telegram-bot を使用した Python
app = Application.builder().token(os.getenv("BOT_TOKEN")).build()
app.run_polling()

ウェブフック (setWebhook) - 本番環境に向いている、低レイテンシー、HTTPS が必須（ポート 443、80、88、または 8443）：

bot.setWebHook('https://yourdomain.com/webhook', { secret_token: SECRET });

開発と小規模なボットはポーリングを選択します。トラフィックが多い本番環境デプロイメントはウェブフックを選択します。

メッセージタイプとフォーマット

sendMessage でテキストを送信します。サポートされているパースモード：

• HTML: <b>bold</b>、<i>italic</i>、<code>code</code>、<pre>block</pre>、<a href="url">link</a>、<tg-spoiler>spoiler</tg-spoiler>
• MarkdownV2: *bold*、_italic_、`code`、```block```、[link](url)、||spoiler||。エスケープが必要：_*[]()~>#+-=|{}.!

エスケープが簡単なため HTML を推奨します。よりシンプルなフォーマットで十分な場合は MarkdownV2 を使用してください。

キーボードとインタラクティブ要素

インラインキーボード - メッセージに付属するボタン：

bot.sendMessage(chatId, 'Choose:', {
  reply_markup: {
    inline_keyboard: [
      [{ text: 'Option A', callback_data: 'a' }, { text: 'Option B', callback_data: 'b' }],
      [{ text: 'Visit Site', url: 'https://example.com' }]
    ]
  }
});

返信キーボード - 入力フィールド下のカスタムキーボード：

bot.sendMessage(chatId, 'Choose:', {
  reply_markup: {
    keyboard: [[{ text: '📊 Stats' }, { text: '⚙️ Settings' }]],
    resize_keyboard: true,
    one_time_keyboard: true
  }
});

callback_query でインラインボタン押下を処理します。callback_data フィールドは 64 バイトに制限されています。常に answerCallbackQuery を呼び出してローディングインジケータを消します。

メディアの送信

// 写真 (file_id、URL、またはアップロード)
bot.sendPhoto(chatId, 'https://example.com/photo.jpg', { caption: 'A photo' });

// ドキュメント
bot.sendDocument(chatId, fs.createReadStream('./file.pdf'), { caption: 'Report' });

// アルバム (2～10 項目)
bot.sendMediaGroup(chatId, [
  { type: 'photo', media: 'https://example.com/1.jpg', caption: 'First' },
  { type: 'photo', media: 'https://example.com/2.jpg' }
]);

ファイルを指定する 3 つの方法：file_id（以前アップロードしたファイルを再利用）、HTTP URL（Telegram がダウンロード）、またはマルチパートアップロード。ファイル制限：アップロード 50MB、Bot API 経由でのダウンロード 20MB。

会話状態

複数ステップのインタラクション（登録、フォーム、ウィザード）では、チャットごとに会話状態を保持します：

• Node.js: Map または Redis を使用して chatId ごとに { step, data } を追跡
• Python: python-telegram-bot の ConversationHandler を使用（組み込み状態機械）

完全な会話フロー実装については reference/patterns_and_examples.md を参照してください。

エラーハンドリング

一般的なエラーシナリオに対応：

• 429 Too Many Requests: レスポンスから retry_after を読み取り、待機後に再試行
• 403 Forbidden: ボットがユーザーからブロックされたか、チャットから削除された
• 400 Bad Request: 無効なパラメータ（description フィールドを確認）
• 409 Conflict: 別のボットインスタンスが同じトークンをポーリングで使用中

レート制限：異なるチャットへは約 30 メッセージ/秒、同じグループへは約 20 メッセージ/分。再試行に指数バックオフを実装してください。

ボットコマンド

Telegram メニューに表示されるコマンドを登録：

bot.setMyCommands([
  { command: 'start', description: 'Start the bot' },
  { command: 'help', description: 'Show help' },
  { command: 'settings', description: 'Bot settings' }
]);

コマンドは BotCommandScope を使用して、特定のチャット、ユーザー、または言語に限定できます。

一般的なパターン

クイックスタート (Node.js)

mkdir my-bot && cd my-bot
npm init -y
npm install node-telegram-bot-api dotenv
echo "BOT_TOKEN=your_token_here" > .env

クイックスタート (Python)

mkdir my-bot && cd my-bot
pip install python-telegram-bot python-dotenv
echo "BOT_TOKEN=your_token_here" > .env

人気のあるライブラリ

言語	ライブラリ	スタイル	最適用途
Node.js	node-telegram-bot-api	コールバック型	シンプルなボット、クイックプロトタイプ
Node.js	grammy	ミドルウェア型	複雑なボット、プラグイン
Node.js	telegraf	ミドルウェア型	成熟したエコシステム
Python	python-telegram-bot	ハンドラー型	フル機能、会話
Python	aiogram	Async ファースト	高性能な非同期ボット

重要な API メソッドカテゴリ

カテゴリ	主要メソッド
メッセージ	sendMessage、sendPhoto、sendVideo、sendDocument、editMessageText、deleteMessage
キーボード	InlineKeyboardMarkup、ReplyKeyboardMarkup、answerCallbackQuery
チャット管理	getChat、banChatMember、promoteChatMember、setChatPermissions
ファイル	getFile、sendMediaGroup、sendDocument
インラインモード	answerInlineQuery と InlineQueryResult* タイプ
支払い	sendInvoice、answerPreCheckoutQuery（Telegram Stars は currency: "XTR" を使用）
ボット設定	setMyCommands、setMyDescription、setWebhook

デプロイメントオプション

• PM2: pm2 start bot.js --name telegram-bot - 自動再起動機能付きプロセスマネージャー
• Docker: docker-compose を使用したコンテナ化デプロイメント
• サーバーレス: Vercel/AWS Lambda 関数としてのウェブフックハンドラー
• VPS: systemd サービスを使用した直接デプロイメント

Docker、PM2、サーバーレスデプロイメント構成については reference/patterns_and_examples.md を参照してください。

セキュリティチェックリスト

• BOT_TOKEN を環境変数に保存
• ウェブフックエンドポイントで X-Telegram-Bot-Api-Secret-Token を検証
• 管理者コマンドのユーザー ID を確認
• ユーザーごとのレート制限を実装
• データベース保存前にユーザー入力をサニタイズ
• すべてのウェブフックエンドポイントに HTTPS を使用
• allowed_updates を必要なタイプのみに制限

参照ファイル

詳細な API ドキュメントと実装パターンについては、以下を参照してください：

• reference/api_methods.md - 100 以上の Bot API メソッドの完全なリスト（メッセージング、チャット管理、ステッカー、支払い、インラインモード、ゲーム、フォーラムトピック、ギフト、パスポート等でカテゴリ分け）
• reference/api_types.md - 200 以上の Bot API タイプと全フィールドの完全なリスト（Update、Message、Chat、User、キーボード、メディアタイプ、支払いタイプ、チャットメンバー、リアクション等）
• reference/patterns_and_examples.md - Node.js と Python の本番対応実装パターン：インラインキーボード、ウェブフック、メディア処理、会話状態管理、データベース統合、管理パネル、多言語サポート、Docker/PM2/サーバーレスデプロイメント、Telegram Stars 支払い、インラインモード

ボットを構築する際は、まず SKILL.md でコア概念を学び、詳細な API 情報または実装パターンが必要に応じて適切な参照ファイルを読み込んでください。