Contents
BotFatherでトークン取得と基本設定
BotFather は Telegram が公式に提供しているボット管理アカウントです。ここで取得した API トークン は、以降の開発・デプロイすべてで必須になるため、最初に安全かつ確実に保存しておくことが重要です。本セクションでは、トークン取得から基本的なボット情報の設定方法までを解説します。
名前・ユーザー名の設定方法
Bot の名前とユーザー名は、ユーザーが検索したりチャットリストに表示されたりする際の「顔」となる要素です。結論 は、分かりやすく一意な文字列を選ぶことです。
- Telegram アプリで
@BotFatherを検索し、スタート（/start）コマンドを送信 /newbotと入力して新規作成モードへ移行- 「ボットの名前」を入力（例：
MyHelper Bot）― これは自由文字列です - 「ユーザー名」は 英数字とアンダースコアのみ、かつ末尾が
bot（大文字小文字は区別されません）で終わる必要があります。例:myhelper_bot,MyHelperBot
ポイント：名前は日本語でも可ですが、ユーザー名は変更できないため最初に十分検討してください。
プライバシーモードの意味と変更手順
プライバシーモードはボットがグループ内で受け取るメッセージの範囲を制御します。結論 は、デフォルト（オン）で開始し、必要に応じてオフにすることです。
- BotFather のチャットで対象ボットを選択（
/mybots→ 対象） - 「Bot Settings」→「Group Privacy」へ進む
Turn offまたはTurn onを選択
ポイント：プライバシーモードをオフにした場合、全メッセージが届くため情報漏洩リスクが高まります。必ずトークンは環境変数で管理し、コード内にハードコーディングしないようにしましょう。
開発環境の構築と推奨言語選択
Telegram ボットは Python と Node.js が特にエコシステムが充実しています。本節では、2026 年時点で安定版として推奨される python‑telegram‑bot 20 系 と telegraf 4 系 のインストール手順を具体例とともに示します。
Python 環境と python-telegram-bot のインストール手順
Python 3.11 以上の仮想環境を作り、公式パッケージをバージョン固定で導入することがベストプラクティスです。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# 1. Python が未インストールなら公式サイトから 3.12 系を取得 # 2. プロジェクトディレクトリ作成・移動 mkdir my_telegram_bot && cd my_telegram_bot # 3. 仮想環境作成（venv 推奨） python3 -m venv .venv source .venv/bin/activate # Windows は .venv\Scripts\activate # 4. パッケージを最新版にアップグレードし、必要ライブラリをインストール pip install --upgrade pip pip install "python-telegram-bot[async]==20.8" python-dotenv |
python‑telegram‑bot[async] を指定すると非同期 API が有効になり、AI 連携時の高並列処理が容易になります。
Node.js と telegraf のセットアップ方法
Node.js 18+（LTS）をベースに npm 初期化後、telegraf と環境変数管理ライブラリを導入します。
|
1 2 3 4 5 6 7 8 9 |
# 1. Node.js が未インストールなら公式サイトから v20 系を取得 mkdir my_telegram_bot_node && cd my_telegram_bot_node # 2. npm プロジェクト初期化 npm init -y # 3. 必要パッケージをインストール npm i telegraf@4 dotenv |
ポイント：
dotenvは.envファイルから API キーやシークレットを安全にロードでき、CI/CD パイプラインでも同様の仕組みで GitHub Secrets と連携可能です。
Telegram Bot API の基礎とハンドラ実装例
Telegram Bot API には Polling（getUpdates） と Webhook の二つの受信方式があります。どちらを選ぶかはローカル開発か本番運用かで判断すると効率的です。本節ではそれぞれの特徴と、Python・Node.js のサンプルハンドラ実装を紹介します。
getUpdates と Webhook の違い・設定方法
以下の表は、代表的な比較項目をまとめたものです。結論 は、ローカルテスト時は Polling、本番環境では HTTPS が必須になる Webhook を利用することです。
| 項目 | Polling (getUpdates) | Webhook |
|---|---|---|
| 実装の簡易さ | ✅ コードだけで完結 | ❌ 公開 HTTPS が必須 |
| レイテンシ | 数秒程度の遅延が発生することも | ⚡ リアルタイムに近い |
| スケーラビリティ | 同時接続数増加で負荷が急上昇 | ✅ 負荷分散しやすく、サーバーレスと相性◎ |
| ローカルテスト向き | ✔️ そのままで動作確認可能 | 🔧 ngrok 等でトンネリングが必要 |
Python（Polling）例
以下は python-telegram-bot の非同期 Polling 実装です。ポイント は、環境変数からトークンを取得し、ハンドラをシンプルに保つことです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
import os, logging from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup from telegram.ext import ( ApplicationBuilder, CommandHandler, MessageHandler, CallbackQueryHandler, filters, ) logging.basicConfig(level=logging.INFO) TOKEN = os.getenv("BOT_TOKEN") app = ApplicationBuilder().token(TOKEN).build() async def start(update: Update, context): await update.message.reply_text( "こんにちは！ /help で使い方を確認してください。", reply_markup=InlineKeyboardMarkup([ [InlineKeyboardButton("ヘルプ", callback_data="help")] ]), ) async def echo(update: Update, context): await update.message.reply_text(f"受け取りました: {update.message.text}") async def button_handler(update: Update, context): query = update.callback_query await query.answer() if query.data == "help": await query.edit_message_text("このボットはテキストをそのまま返すだけです。") app.add_handler(CommandHandler("start", start)) app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo)) app.add_handler(CallbackQueryHandler(button_handler)) if __name__ == "__main__": app.run_polling() |
Node.js（Polling）例
telegraf を用いた同等の実装です。環境変数は dotenv 経由でロードします。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
require('dotenv').config(); const { Telegraf, Markup } = require('telegraf'); const bot = new Telegraf(process.env.BOT_TOKEN); bot.start((ctx) => { ctx.reply( 'こんにちは！ /help で使い方を確認してください。', Markup.inlineKeyboard([ Markup.button.callback('ヘルプ', 'HELP') ]) ); }); bot.on('text', (ctx) => { ctx.reply(`受け取りました: ${ctx.message.text}`); }); bot.action('HELP', async (ctx) => { await ctx.answerCbQuery(); await ctx.editMessageText('このボットはテキストをそのまま返すだけです。'); }); bot.launch(); |
ポイント：どちらの実装でも
dotenv/python-dotenvにより環境変数からトークンを取得し、コードに直接書かないよう徹底してください。
AI 連携とセキュリティベストプラクティス
AI 機能を組み込むことで、単なるエコーボットを自然言語対話ボットへ拡張できます。2026 年現在、OpenAI GPT‑4o と Anthropic Claude 3.5 Sonnet が主流です。本節では API 呼び出し例と、安全なシークレット管理手法をまとめます。
OpenAI と Claude API を呼び出すサンプルコード
Python（非同期）
以下は aiohttp を使った非同期リクエストの例です。重要ポイント は、タイムアウトやエラーハンドリングを忘れないことです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
import os, aiohttp, asyncio from telegram import Update from telegram.ext import ContextTypes OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") CLAUDE_API_KEY = os.getenv("CLAUDE_API_KEY") async def chat_gpt(update: Update, context: ContextTypes.DEFAULT_TYPE): user_msg = update.message.text async with aiohttp.ClientSession() as session: # OpenAI GPT‑4o 呼び出し例 try: resp = await session.post( "https://api.openai.com/v1/chat/completions", headers={"Authorization": f"Bearer {OPENAI_API_KEY}"}, json={ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": user_msg}], "max_tokens": 200, }, timeout=15, ) data = await resp.json() reply = data["choices"][0]["message"]["content"] except Exception as e: reply = f"OpenAI 呼び出しでエラーが発生しました: {e}" await update.message.reply_text(reply) |
Node.js（Promise）
node-fetch を利用した非同期呼び出し例です。ポイント は、ステータスコードの確認と例外処理です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
require('dotenv').config(); const fetch = require('node-fetch'); const { Telegraf } = require('telegraf'); const bot = new Telegraf(process.env.BOT_TOKEN); bot.on('text', async (ctx) => { const userMsg = ctx.message.text; try { const response = await fetch('https://api.anthropic.com/v1/messages', { method: 'POST', headers: { 'x-api-key': process.env.CLAUDE_API_KEY, 'content-type': 'application/json', }, body: JSON.stringify({ model: 'claude-3.5-sonnet-20240620', max_tokens: 256, messages: [{ role: 'user', content: userMsg }], }), }); if (!response.ok) throw new Error(`HTTP ${response.status}`); const data = await response.json(); ctx.reply(data.content[0].text); } catch (err) { ctx.reply(`Claude 呼び出しでエラーが発生しました: ${err.message}`); } }); bot.launch(); |
環境変数・.env、GitHub Secrets による安全なシークレット管理
.env ファイルはローカル開発時の便利な手段ですが、本番環境では 絶対にリポジトリに含めない ことが前提です。以下のフローでシークレット漏洩を防止できます。
- プロジェクト直下に
.env.exampleを作成し、キー名だけを書いて共有
dotenv
BOT_TOKEN=your_telegram_bot_token
OPENAI_API_KEY=sk-...
CLAUDE_API_KEY=anthropic-... - 開発者は
.env.exampleをコピーして.envを自分の環境で作成し、.gitignoreに.envを追加 - 本番デプロイ先（Vercel・Cloud Run・Railway など）では プラットフォーム提供のシークレット機能 に同名変数を登録するだけで、コードからは
os.getenv()/process.envで取得できます。 - GitHub Actions を利用する場合は
secrets.BOT_TOKEN等をenv:にマッピングし、CI の実行時にのみ環境変数として注入します。
この手順に従えば コードリポジトリに認証情報が残らない だけでなく、キーのローテーションや権限最小化も容易になります。
ローカルテスト・デバッグとクラウドデプロイ
開発サイクルを高速化するためには、ローカル環境でも Webhook を試せる仕組みが必要です。また、本番へ移行するときの主要クラウドサービス別注意点も合わせて解説します。
ngrok と Telegram Debug Bot を使ったローカル Webhook テスト
ngrok はローカルポートをインターネット上に公開するツールで、Telegram の Webhook 設定とデバッグに最適です。手順は次の通り です。
ngrok http 8080（またはボットがリッスンしているポート）を実行し、HTTPS URL を取得- 以下のコマンドで Webhook を設定（Python の例）
bash
curl -F "url=https://<your-ngrok-id>.ngrok.io/webhook" \
"https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" - 公式デバッグボット
@BotDebugに/testコマンドを送信し、受信した JSON ペイロードが期待通りか確認 - テスト完了後は
ngrok disconnectまたはプロセス終了でトンネルを閉じます
ポイント：無料プランは毎回 URL が変わるため、テストのたびに Webhook 再設定が必要です。頻繁にデバッグしたい場合は有料プランで固定サブドメインを取得すると手間が省けます。
Vercel、Google Cloud Run、Railway へのデプロイ手順と注意点
主要クラウドプラットフォームの特徴と、共通するデプロイフローをまとめました。結論 は、HTTPS が自動で提供される環境を選び、シークレットは各サービスの管理画面から設定することです。
| プラットフォーム | 主な特徴 | デプロイ時の必須手順 |
|---|---|---|
| Vercel (Serverless) | Node.js が標準、GitHub 連携がシンプル | vercel.json に関数設定を書き、Dashboard の Environment Variables にキーを登録 |
| Google Cloud Run | 完全マネージドコンテナ、スケール自動化 | Dockerfile を用意し、gcloud builds submit → gcloud run deploy。シークレットは Cloud Secret Manager か環境変数で注入 |
| Railway | UI が直感的、無料枠で 500h/月 使用可 | 「Deploy from Git」→リポジトリ接続後、Settings の Environment にキーを追加。起動コマンドは python -m src.main 等 |
デプロイ共通チェックリスト
- HTTPS：Webhook URL は必ず有効な TLS 証明書付きであること（Vercel・Cloud Run は自動提供）。
- 環境変数漏洩防止：公開設定はオフにし、GitHub Secrets のみ使用。
- スケール上限：無料枠は同時実行数が制限されるため、トラフィック増加前に有料プランへの移行計画を立てること。
運用フェーズ：エラーハンドリング・再起動・アップデート
本番運用では安定稼働と迅速な障害復旧が求められます。以下の手法でプロセス管理、ログ取得、権限変更を体系化しましょう。
PM2 と systemd によるプロセス管理と自動再起動戦略
PM2（Node.js 推奨）
PM2 は Node.js アプリケーション向けのプロセスマネージャで、クラスターモードやログローテーション機能が充実しています。
|
1 2 3 4 5 |
npm i -g pm2 pm2 start bot.js --name telegram-bot --env production pm2 save # 起動情報を永続化 pm2 startup systemd # OS 再起動時に自動復帰 |
ecosystem.config.js の例：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
module.exports = { apps: [ { name: "telegram-bot", script: "./bot.js", instances: "max", // CPU コア数だけプロセスを立ち上げる exec_mode: "cluster", // クラスターモードで負荷分散 env_production: { NODE_ENV: "production" }, watch: false, max_memory_restart: "200M", restart_delay: 3000 // 再起動間隔（ミリ秒） } ] }; |
systemd（Python・汎用）
Linux 系サーバーでの標準的なプロセス管理です。EnvironmentFile に .env を指定すれば、シークレットは自動でロードされます。
サービスファイル例 (/etc/systemd/system/telegram-bot.service)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
[Unit] Description=Telegram Bot Service After=network.target [Service] User=botuser WorkingDirectory=/opt/telegram_bot EnvironmentFile=/opt/telegram_bot/.env ExecStart=/opt/telegram_bot/.venv/bin/python -m src.main Restart=on-failure RestartSec=5 StandardOutput=journal StandardError=journal [Install] WantedBy=multi-user.target |
デプロイ後の操作:
|
1 2 3 4 5 |
sudo systemctl daemon-reload sudo systemctl enable telegram-bot # 起動時自動実行 sudo systemctl start telegram-bot # 今すぐ起動 sudo journalctl -u telegram-bot -f # リアルタイムログ確認 |
ポイント：
Restart=on-failureにより例外が投げられた場合でも自動で再起動します。journalctlが標準出力・エラーを統合的に管理できるので、障害調査が容易です。
ログ取得と BotFather からの権限変更手順
- ログ取得
- クラウド側は各プラットフォームのロギング機能（Vercel Logs、Cloud Logging）に標準出力を流すだけで可視化できます。
-
ファイルベースが必要な場合は
logrotateでサイズ上限と世代管理を設定し、過去ログは圧縮保存します。 -
BotFather の権限変更
- ボットに「メッセージ削除」や「グループ管理者権限」が必要な場合は、対象のグループでボットを管理者として追加し、手動で権限を付与します。
-
BotFather の UI では権限設定はできない点に注意してください。変更は即時反映され、再起動は不要です。
-
アップデートとロールバック
- 新しいコードをプッシュ → CI が自動ビルド・デプロイ（Vercel/Cloud Run 等）。
- ステージング環境で検証後、本番へマージ。
- 問題が発生したら
git revertか Docker イメージの過去タグにロールバックし、再デプロイするだけで復旧可能です。
ベストプラクティス：外部 API キーや DB 接続情報を変更するときは「マイグレーション」スクリプトを別途用意し、ゼロダウンタイムデプロイを目指すと運用リスクが大幅に低減します。
まとめ
- BotFather で取得したトークンは
.envまたは GitHub Secrets に安全に保管し、名前・プライバシーモードは用途に合わせて適切に設定する。 - 開発言語は Python（python‑telegram‑bot） または Node.js（telegraf） を選び、仮想環境／npm 初期化で依存管理を徹底する。
- Polling はローカルテスト向き、Webhook は本番デプロイに必須であり、ngrok と Debug Bot でローカル Webhook を手軽に検証できる。
- AI 連携は OpenAI GPT‑4o・Claude 3.5 Sonnet が主流。API キーは環境変数で管理し、非同期リクエストで高速応答を実現する。
- デプロイ先は Vercel Serverless, Google Cloud Run, Railway のいずれかを選択し、HTTPS とシークレット設定に注意する。
- 運用フェーズでは PM2（Node.js）または systemd（Python）で自動再起動・ログ取得を行い、エラーハンドリングとロールバック手順を整備すれば安定稼働が可能になる。
これらのステップを順に実施すれば、2026 年最新版のセキュリティ基準と AI 機能を備えた Telegram チャットボット を迅速かつ安全に構築・デプロイできます。