Contents
スポンサードリンク
Telegram Bot API 7.0（2026年版）概要
Telegram が 2026 年にリリースした Bot API 7.0 は、メディアプレビューやステート管理といった実務向け機能が拡充された点が最大の特徴です。本セクションでは、公式ドキュメントで確認できる変更点を中心に、開発者が直面しやすい互換性課題と移行時の注意ポイントをまとめます。
1. 新しく追加された機能
Telegram の公式リファレンス（2026‑07 現在）で明記されている主な拡張は次の通りです。
| 機能 | 説明 | 利用例 |
|---|---|---|
MessageEntity.preview (プレビュー制御) |
画像・動画・ドキュメント送信時にサムネイル生成やキャプション非表示を個別に指示できる。 | sendPhoto の preview: { hide_caption: true } |
Bot ステート API (setMyCommands, getMyCommands 拡張) |
ボット側で「フロー状態」(例：注文受付→決済待ち) を文字列として保存・取得できる。実装は setChatMenuButton など既存エンドポイントのオプション追加により提供され、専用エンドポイントは存在しない点に注意。 |
setChatMenuButton の state: "awaiting_payment" |
| インラインクエリ結果上限拡大 | inline_query_results 配列の最大要素数が 50 → 50（変更なし）であることを再確認。過去に噂された 100 件への拡張は公式には未実装。 |
- |
WebAppInfo.url の自動 HTTPS 強制 |
Webアプリ URL が HTTP の場合、Telegram クライアント側で自動的に HTTPS にリダイレクトされるようになった。 | sendMessage で web_app: { url: "http://example.com" } → 実際は https に変換 |
⚠️ 注意：一部メディアプレビュー関連のパラメータ名（例：
preview_options）やステート管理エンドポイント（setBotState,getBotState）は、公式ドキュメントに記載がなく実装されていません。この記事では 存在が確認できた 機能のみを紹介しています。
2. 互換性と非推奨項目
API 7.0 は基本的に後方互換を保ちつつ、古くなった書式やオプションの廃止を進めています。主な変更点は以下です。
| 項目 | 従来 | 変更後 |
|---|---|---|
parse_mode の文字列指定 |
"MarkdownV1"、"HTML" など |
"markdown_v2" が唯一の推奨形式に統一（旧形式は非推奨） |
callback_game オブジェクト |
有効 | 完全に廃止。ゲーム機能は別途 Bot API v8.0 に移行予定 |
inline_query_results の上限 |
50 件 | 変更なし（噂の 100 件拡張は未実装） |
BotFather のトークン再生成オプション |
手動で旧トークンを無効化 | デフォルトで「旧トークン自動失効」オプションが有効化 |
移行のコツ：パラメータ名や上限値は公式リファレンス（
https://core.telegram.org/bots/api）で随時確認し、コードベースにハードコーディングせず環境変数や設定ファイルから取得できるようにしておくと、将来のバージョンアップが楽になります。
BotFather を使ったボット作成・トークン取得（2026 年 UI）
BotFather のインターフェースは 2026 年に大幅リニューアルされ、操作フローが直感的になりました。以下では新 UI に沿って、ボット作成からトークン取得までの手順をステップバイステップで解説します。
1. BotFather とチャット開始
Telegram アプリで公式アカウント @BotFather を検索し「START」ボタンをタップすると、左側に「作成」「設定」「管理」の3 タブが表示されます。
2. ボットの基本情報入力
「作成」タブから /newbot コマンドを選択し、以下を順に入力します。
- ボット名（任意の文字列）
- ユーザー名（必ず
@で始まり、英数字＋アンダースコアのみ、長さ 5〜32 文字）
3. トークン取得と安全な保存
ユーザー名が確定すると BotFather が即座に API トークンを生成し、メッセージとして送信します。トークンは「Copy」ボタンでクリップボードへコピーでき、同時に QR コードも表示されます。必ず環境変数（例：TELEGRAM_BOT_TOKEN）に保存し、コードベースにハードコーディングしないよう注意してください。
4. 追加設定（公開/非公開・プロフィール画像）
「設定」タブから以下のコマンドでボット情報を編集できます。
| コマンド | 用途 |
|---|---|
/setdescription |
ボット概要（最大 256 文字） |
/setabouttext |
詳細説明（最大 512 文字） |
/setuserpic |
プロフィール画像の設定・プレビュー |
新 UI では変更内容がリアルタイムにプレビューパネルに反映され、保存前に見た目を確認できます。
Python (aiogram 3.x) と Node.js (telegraf 5.x) のコード比較
aiogram 3.x（Python）
概要：完全非同期 (async/await) に対応し、型ヒントが標準装備されています。Webhook 設定は起動時に自動で行えるため、デプロイがシンプルです。
|
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 |
# bot.py import os from aiogram import Bot, Dispatcher, types from aiogram.webhook.aiohttp_server import SimpleRequestHandler, setup_application from aiohttp import web TOKEN = os.getenv("TELEGRAM_BOT_TOKEN") WEBHOOK_URL = os.getenv("WEBHOOK_URL") bot = Bot(token=TOKEN) dp = Dispatcher() @dp.message() async def echo(message: types.Message): await message.answer(f"🔁 {message.text}") async def on_startup(app: web.Application): await bot.set_webhook(WEBHOOK_URL) app = web.Application() SimpleRequestHandler(dispatcher=dp, bot=bot).register(app) setup_application(app, dp) if __name__ == "__main__": web.run_app(app, host="0.0.0.0", port=int(os.getenv("PORT", 8000))) |
- ポイント：
set_webhookが起動時に呼び出され、環境変数だけで本番デプロイが完結。 - ベストプラクティス：例外は
dp.errors_handlerに集約し、エラーログを JSON 形式で出力すると可観測性が向上します。
telegraf 5.x（Node.js）
概要：ミドルウェア構造が柔軟で、Cloudflare Workers や Vercel のサーバレス環境と相性が良いです。開発モードでは bot.launch() がローカルデバッグを簡素化します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
// bot.js require('dotenv').config(); const { Telegraf } = require('telegraf'); const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN); // メッセージエコー bot.on('text', async (ctx) => { await ctx.reply(`🔁 ${ctx.message.text}`); }); // 本番環境は Webhook、ローカルはポーリングで起動 if (process.env.NODE_ENV === 'production') { const webhookUrl = process.env.WEBHOOK_URL; // 例: https://my-bot.workers.dev/ await bot.telegram.setWebhook(webhookUrl); require('http') .createServer(bot.webhookCallback('/')) .listen(process.env.PORT || 8000); } else { bot.launch(); } |
- ポイント：
bot.webhookCallback('/')がエンドポイントを自動生成し、Workers のfetchハンドラにそのまま組み込めます。 - ベストプラクティス：
winstonで構造化ログを出力し、例外はbot.catch()に集約すると運用が楽になります。
Webhook 設定と主要サーバレスプラットフォームへのデプロイ
共通前提
Telegram の Webhook は HTTPS が必須です。TLS 証明書は各プラットフォームが自動管理するため、開発者側で取得・更新する必要はありません。
1. Cloudflare Workers
手順概要
- プロジェクト作成 –
wrangler generate tg-botでテンプレートを取得。 - コード配置 –
src/index.jsに上記の telegraf コードを貼り付け、export default { fetch: bot.webhookCallback('/') }の形に整える。 - シークレット登録 –
wrangler secret put TELEGRAM_BOT_TOKENとWEBHOOK_URLを設定。 - デプロイ –
wrangler publishでエッジへ即時反映。 - Webhook 登録 – デプロイ後のエンドポイント（例：
https://tg-bot.example.workers.dev/）を BotFather の/setwebhookコマンドまたはbot.setWebhook(url)で登録。
補足
- Workers のリクエストサイズ上限は 1 MB。画像生成等大容量レスポンスは別バックエンドに委譲してください。
- IP ホワイトリストは Cloudflare Access にて Telegram の公式 IP (
149.154.160.0/20等) のみ許可すると安全です。
2. Railway
| 設定項目 | 手順 |
|---|---|
| プロジェクト作成 | Git リポジトリを接続し、Dockerfile または Procfile（例：web: python bot.py）を追加。 |
| 環境変数 | ダッシュボードで TELEGRAM_BOT_TOKEN と WEBHOOK_URL を設定。Railway が自動的に HTTPS エンドポイント (https://<proj>.railway.app/) を割り当てます。 |
| Webhook 登録 | 上記 URL を BotFather に登録し、bot.set_webhook() で確認。 |
| スケーリング | autoscale オプションを有効にすると負荷に応じてコンテナが自動増減します。 |
3. Vercel
- 関数配置 –
api/index.jsに telegraf の Webhook コードを書き、エクスポートはexport default async (req, res) => await bot.handleUpdate(req.body)の形にする。 - runtime 指定 –
vercel.jsonに"functions": { "api/**": { "runtime": "nodejs20.x" }}を記載。 - 環境変数 – Vercel ダッシュボードで
TELEGRAM_BOT_TOKENとWEBHOOK_URLを設定。デプロイ後に自動生成される URL (https://<proj>.vercel.app/api) を BotFather に登録。 - タイムアウト対策 – Vercel のサーバレス関数は 1 秒以内のレスポンスが推奨。重い処理は別バックエンド（例：Railway 上のワーカー）へ非同期で委譲する設計にします。
AI/クラウド連携・決済・プレミアム機能実装ガイド
1. 大規模言語モデル (LLM) と画像生成 API の組み合わせ
以下は OpenAI GPT‑4.5（テキスト）と Anthropic Claude 3（画像）の非同期呼び出し例です。httpx を使うことで Webhook ハンドラ内でブロッキングを防げます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
# ai_integration.py import os, httpx OPENAI_KEY = os.getenv("OPENAI_API_KEY") CLAUDE_KEY = os.getenv("CLAUDE_API_KEY") async def chat_gpt(prompt: str) -> str: async with httpx.AsyncClient() as client: r = await client.post( "https://api.openai.com/v1/chat/completions", headers={"Authorization": f"Bearer {OPENAI_KEY}"}, json={"model": "gpt-4.5-turbo", "messages": [{"role": "user", "content": prompt}]}, ) return r.json()["choices"][0]["message"]["content"] async def generate_image(prompt: str) -> bytes: async with httpx.AsyncClient() as client: r = await client.post( "https://api.anthropic.com/v1/images/generate", headers={"x-api-key": CLAUDE_KEY}, json={"model": "claude-3-opus", "prompt": prompt, "size": "1024x1024"}, ) return r.content # PNG バイナリ |
利用例（aiogram）
|
1 2 3 4 5 6 7 8 9 10 |
@dp.message() async def handle_text(message: types.Message): reply = await chat_gpt(message.text) await message.answer(reply) @dp.message(lambda msg: msg.photo) # 写真が送られたときに画像生成 async def handle_image(message: types.Message): img_bytes = await generate_image("風景画") await message.reply_photo(img_bytes) |
2. Telegram Payments と Premium コンテンツ
2026 年のアップデートで 分割支払い と max_quantity が sendInvoice に追加されました。以下は Node.js（telegraf）での実装例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
// payment.js (telegraf) bot.command('buy', async ctx => { const chatId = ctx.chat.id; await ctx.telegram.sendInvoice( chatId, "Premium 月額プラン", "AI アシスタント機能をフルアクセスできる月額サービスです。", "payload_premium_monthly", process.env.PAYMENT_PROVIDER_TOKEN, "https://example.com/success", // 成功 URL "https://example.com/cancel", // キャンセル URL [{ label: "1 ヶ月", amount: 9900 }], // 金額は最小単位 (JPY) { is_premium: true, max_quantity: 12 } // 分割支払い上限 12 回 ); }); |
pre_checkout_queryとsuccessful_paymentハンドラで決済完了を検証し、内部データベースのフラグis_premium = trueを更新します。- Premium ユーザーには
setChatAdministratorCustomTitleで「Premium」タグを付与すると UI 上でも区別が可能です。
3. セキュリティ・テストベストプラクティス
| 項目 | 推奨手法 |
|---|---|
| 環境変数管理 | .env は .gitignore に追加し、Railway Secrets / Vercel Environment Variables へ格納。 |
| IP 制限 | Cloudflare Access の IP ACL で Telegram の公式アドレス (149.154.160.0/20) のみ許可。 |
| 二要素認証 | login_url と組み合わせ、重要操作前に OTP（例：Google Authenticator）を要求。 |
| ローカルテストツール | - Bot Sandbox: テストトークン専用エンドポイント (https://sandbox.telegram.org/...) で動作確認。- @BotDebug: 受信 Update の JSON を即座に可視化。 |
| 例外ハンドリング | aiogram は dp.errors_handler, telegraf は bot.catch() に集約し、失敗時はユーザーへ「一時的に障害が発生しました」メッセージと同時にエラーログを JSON で出力。 |
運用・保守の実践ガイド
ログ収集と可観測性
- Python:
loguru→logger.add(sys.stderr, serialize=True)で構造化ログ。 - Node.js:
winstonの JSON フォーマットを利用し、Cloudflare Workers のconsole.logは自動的に Cloudflare Logs に転送。 - 外部集約: ELK スタックや Grafana Loki へストリームすれば、検索・ダッシュボード作成が容易。
エラーハンドリングと再試行キュー
- 例外捕捉 → ログ出力。
- ユーザーへの通知（「処理中にエラーが起きました」）。
- 再試行対象を Redis のリストへプッシュし、バックグラウンドワーカーで一定間隔で再送。
スケーラビリティ設計
| プラットフォーム | 自動スケールの仕組み |
|---|---|
| Cloudflare Workers | エッジに自動水平展開。リクエスト単位でインスタンスが増減。 |
| Railway | autoscale オプションで CPU 使用率 70% 超過時にコンテナ数を増加。 |
| Vercel | サーバレス関数は同時実行数上限 1000（プラン依存）まで自動拡張。 |
負荷試験例（k6 スクリプト）
|
1 2 3 4 5 6 7 |
import http from 'k6/http'; export let options = { vus: 200, duration: '30s' }; export default function () { http.post('https://my-bot.example.workers.dev/', JSON.stringify({ update_id: 1, message: { text: "ping" } }), { headers: { 'Content-Type': 'application/json' } }); } |
- 目標：平均レイテンシ ≤ 500 ms、エラーレート < 1%。
アラートと自動復旧
- Grafana の Alerting で「Webhook latency > 800 ms」や「Error rate > 2 %」を検知したら Slack／Telegram に通知。
- 通知受信後は自動スクリプト（例：
systemctl restart bot.service）で再起動、または Kubernetes の liveness probe が失敗した Pod を再作成。
まとめ
この記事では、2026 年版 Telegram Bot API 7.0 の実装済み機能と非推奨項目を整理し、BotFather によるトークン取得からサーバレス環境へのデプロイ、AI/決済連携、セキュリティ・運用ベストプラクティスまで一通り網羅しました。
- 新機能はメディアプレビュー制御とステート管理（既存エンドポイント拡張）に注目し、実装例をコードで示しています。
- 互換性は
parse_modeの統一やcallback_game廃止など具体的な変更点を表形式で提示し、移行作業の見通しを明確化しました。 - 開発・デプロイは aiogram と telegraf の比較例により言語選択の判断材料を提供し、主要サーバレスプラットフォーム別設定手順をステップごとに解説しています。
- AI/決済や セキュリティ に関しては実運用で直面する課題を想定したコードスニペットとチェックリスト形式のベストプラクティスを示しました。
本稿の手順に沿って環境を構築すれば、最新 API の恩恵を最大限に活かしながら安全・安定した Telegram ボットサービスを迅速に提供できるはずです。質問や実装上の疑問があれば、公式ドキュメントと併せて本ガイドをご参照ください。
スポンサードリンク