Telegram Serverless
Telegram Serverless (core.telegram.org)
要約
Telegramは、ボットやミニアプリのバックエンドコードをTelegramインフラストラクチャ上で直接実行できる「Telegram Serverless」を発表しました。これにより、サーバーのプロビジョニング、コンテナの維持、スケーリングの心配が不要になります。開発者はプレーンなJavaScriptモジュールを記述し、単一コマンドでデプロイするだけで、Telegramが高速で隔離されたV8サンドボックス内でコードを実行します。データベースやBot APIへのアクセスも組み込まれており、開発ワークフローを大幅に簡素化します。
全文翻訳
Telegram Serverless
このページの機械可読版: /bots/serverless.md。
Telegram Serverlessを使用すると、ボットやミニアプリのバックエンドコードをTelegramのインフラ上で直接実行できます。サーバーのプロビジョニング、コンテナの維持、スケーリングの心配は不要です。プレーンなJavaScriptモジュールを記述し、単一のコマンドでデプロイすると、TelegramはBot APIの隣にある高速で隔離されたV8サンドボックスで実行します。これには組み込みデータベースも含まれています。
ボットをVPS、クラウドファンクション、またはホスティングパネルに接続して /start に応答させたことがあるなら、それはもう必要ありません。
このページについて
最近の変更
2026年10月6日
- ミニアプリホスティングを追加しました。ミニアプリのフロントエンドのビルド出力は、ボットと共にデプロイされ、
https://app<app_id>.tgcloud.ai/で提供されます。 - ミニアプリがTelegram.WebApp.Serverless.callで呼び出す関数であるエンドポイントを追加しました。
- CLIをバージョン0.2.0に更新しました。
- プロジェクト設定ファイルtgcloud.jsoncを追加しました。
- プロジェクトモジュールは、
.js拡張子を付けて相対パスでインポートできるようになりました。 - すべてのモジュールは現在
tgcloud/フォルダにあります。以前のバージョンのCLIで作成されたプロジェクトでは、一度npx tgcloud upgradeを実行してください。
サーバーレスの利点
Telegramボットは、基本的にアップデートに反応するプログラムです。従来は、常に稼働しており、到達可能で、安全な場所にそのプログラムをホストし、それを維持する必要がありました。Telegram Serverlessは、そのレイヤーを完全に削除します。
- インフラ不要。レンタル、パッチ適用、監視が必要なマシンはありません。コードはオンデマンドで実行され、ボットのトラフィックに合わせて自動的にスケーリングします。
- 「すぐに使える」機能。Telegram Bot API、SQLiteバックエンドのデータベース、アウトバウンドHTTPは、どのモジュールからでもすぐに利用できます。インストール不要、認証情報の配線も不要です。
- 高速で隔離された実行。各呼び出しは軽量なV8アイソレートで実行され、Telegram自身のシステムに近い場所にあるため、Bot APIやデータベースへの呼び出しは迅速かつ信頼性が高くなります。
- 実際の開発ワークフロー。プロジェクトは、バージョン管理下にあるローカルフォルダに存在します。ファイルを編集し、変更内容を正確に確認し、アトミックにデプロイし、レビュー済みのマイグレーションでデータベーススキーマを前進させます。これは、他のすべてのものと同様に、あなたが既に作業している方法です。
メンタルモデル
3つの場所で作業し、それらはきれいにマッピングされます。
| 場所 |
| --- | --- |
| プロジェクトフォルダ |
| クラウド |
| tgcloud CLI |
SSH接続は一切不要です。ローカルでファイルを編集し、npx tgcloud push を実行すると、プラットフォームがそれ以降を処理します。ボットのトラフィックはデプロイされたモジュールによって処理され、データベースは呼び出し間で永続化されます。
A project has just four kinds of code, all inside one tgcloud/ folder:
tgcloud/
├─ endpoints/ # ミニアプリが呼び出す関数
├─ handlers/ # Telegramのアップデートタイプに反応する関数
├─ lib/ # どこからでもインポートできる共有コード
└─ schema.js # データベーステーブル
アップデート(メッセージ、ボタンのクリック、インラインクエリなど)が到着すると、Telegramはそれを対応するハンドラ(handlers/message.js、handlers/callback_query.jsなど)にルーティングし、そのデフォルトエクスポートを呼び出します。その関数はSDKを介してBot APIとデータベースと通信し、値を返します。これが全体のループです。対応するハンドラがないアップデートは無視されるため、必要なハンドラのみを追加します。
A Mini App is optional. If your bot has one, its front-end lives in the same project, next to tgcloud/. Serverless hosts its build output and runs the endpoints/ it calls. See Mini App front-end。
クイックデモ
以下は、完全に動作するデモボットです。すべてのメッセージに応答し、各チャットから受信したメッセージの数を記憶します。
tgcloud/schema.js
import { table, integer } from 'sdk/db';
export const counters = table('counters', {
chatId: integer('chat_id').primaryKey(),
seen: integer('seen').notNull().default(0),
});
tgcloud/handlers/message.js
import { api, db } from 'sdk';
import { sql } from 'sdk/db';
import { counters } from '../schema.js';
export default async function (message) {
const chatId = message.chat.id;
// カウンターを挿入するか、このチャットに既に存在する場合はインクリメントします。
// .returning() を介して、同じステートメントで結果の行を取得します。
const [row] = await db.insert(counters)
.values({ chatId, seen: 1 })
.onConflictDoUpdate({
target: counters.chatId,
set: { seen: sql`${counters.seen} + 1` },
})
.returning()
.run();
await api.sendMessage({
chat_id: chatId,
text: `Hello! I've seen ${row.seen} message(s) from you.`,
});
}
デプロイします:
npx tgcloud push # モジュールをアップロード
npx tgcloud migrate # `counters` テーブルを作成
これで、永続的な状態を持つライブボットが、サーバーなしで完成しました。この中のすべて(api、db、table() DSL)は、以下のセクションで説明されています。
Serverlessは、Telegramボットおよびミニアプリ向けの汎用バックエンドであり、特定の種類のアプリのテンプレートではありません。以下のような用途に最適です。
- 会話型AIボット: ユーザーごとの状態をデータベースに保存する必要があるもの。
- ミニアプリバックエンド: ユーザーデータを保存し、動的なコンテンツを提供するもの。
- ゲームとツール: リーダーボード、クイズなど。
- 自動化と統合: サードパーティのHTTP APIを呼び出し、結果をチャットにプッシュするもの。
はじめに
このウォークスルーでは、空のフォルダからメッセージに応答し、データを保存するライブボットを作成するまでの手順を説明します。Node.js 18以降がインストールされており、@BotFatherでボットが登録されていることを前提としています。最終的には、日常的に使用するすべてのコマンド(push、migrate、run、status)を使用することになります。
まず、Serverlessをオンにしてください。 @BotFatherで、ボットを開き → Serverless を選択してオンにします。これにより、このボットの機能がオンになり、CLIアクセス、ハンドラ、ライブラリ、データベースへのアクセスが有効になります。
1. プロジェクトの作成
最も簡単な開始方法は、プロジェクト作成ツールを使用することです。これにより、プロジェクトの雛形が作成され、CLIがプロジェクトにインストールされます。
npm create @tgcloud/bot example_bot
cd example_bot
引数はターゲットフォルダです。. を渡すと現在のフォルダに雛形を作成します。既存のフォルダでも機能し、既存のファイルは上書きしません。
これにより、すぐに編集できるプロジェクトが作成されます。
example_bot/
├─ tgcloud/ # プラットフォームが実行するすべてのもの
│ ├─ handlers/
│ │ └─ message.js # スターターメッセージハンドラ(テキストをエコーバック)
│ ├─ lib/ # 共有モジュールはここ(最初は空)
│ └─ schema.js # データベーステーブル
├─ docs/
│ └─ tgcloud-sdk.md # SDKリファレンス(あなたとAIツール用)
├─ AGENTS.md # AIコーディングアシスタント向けのオリエンテーション
├─ package.json
└─ tgcloud.jsonc # プロジェクト設定
雛形化されたファイルは自己文書化されており、それぞれに次に何ができるかのコメント付き例が含まれています。
The CLI installs into the project as a local dev-dependency, so you run it with npx tgcloud <command> (npx finds the copy in your project's node_modules), or through the npm run shortcuts the scaffold adds to package.json (npm run deploy, npm run status). By default there is no global tgcloud on your PATH.
You can also install it globally — npm install -g @tgcloud/cli — if you'd rather type a bare tgcloud from anywhere. That's handy for running tgcloud init in any empty folder, and it's what shell tab‑completion needs. Either way you get the same project.
ミニアプリを構築しますか? フロントエンドから開始してください。通常のツールで作成し、そのフォルダでプロジェクト作成ツールを実行します。Mini App front-endを参照してください。
2. ボットのリンク
各プロジェクトは1つのボットに紐付けられます。login コマンドで接続します。このコマンドはCLIアクセスートークン(@BotFather → ボット → Serverless → CLI Access → Access token — ボットのAPIトークンとは別のトークン)を求め、ローカルに保存します。
npx tgcloud login
トークンは app<id>:<secret> の形式です。CLIはそれを .tgcloud/ に保存し、秘密の部分は決して表示しません。ログイン時のみ求められます。CIでのトークン解決については、認証を参照してください。
3. 確認
2つのコマンドで、いつでも状況を確認できます。どちらもオフラインで動作します。
npx tgcloud status # ローカルとデプロイ済みのコピーとの差分を表示
npx tgcloud diff # 行ごとの差分を表示
init 直後では、すべてが新しく、何もデプロイされていません。status はアップロード待ちのスターターファイルを表示します。
4. デプロイ
モジュールをクラウドに送信します。
npx tgcloud push
push は、変更されたすべてのモジュールを1つのアトミックなバッチでアップロードし、クラウドに現在保持されているもののローカルレコードを更新します。ボットはライブです。Telegramでボットを開いてメッセージを送信してみてください。スターターハンドラがそれをエコーバックします。
デプロイはデータベースに一切触れません。 コードのプッシュとデータベーススキーマの変更は意図的に別々のステップになっているため、コードのデプロイでデータ移行が予期せず発生することはありません。次のステップはそのためのものです。
5. データベーステーブルの追加
ボットに何かを記憶させましょう。tgcloud/schema.js を開き、テーブルを宣言します。
import { table, integer, text, sql } from 'sdk/db';
export const messages = table('messages', {
id: integer('id').primaryKey({ autoIncrement: true }),
chatId: integer('chat_id').notNull(),
text: text('text'),
created: integer('created_at', { mode: 'timestamp' }).default(sql`(unixepoch())`),
});
スキーマをデプロイし、次にデータベースに適用します。
npx tgcloud push # 新しいスキーマをアップロード
npx tgcloud migrate # `messages` テーブルを作成
push はスキーマが同期していないことを報告し、保留中の変更を表示しますが、何も適用しません。migrate は変更をステップバイステップで案内し、確認後にテーブルを作成します。この2段階モデルと、削除などのよりリスクの高い変更がどのように扱われるかについては、マイグレーションを参照してください。
6. データの保存と読み取り
次に、ハンドラからテーブルを使用します。tgcloud/handlers/message.js を編集します。
import { api, db } from 'sdk';
import { eq } from 'sdk/db';
import { messages } from '../schema.js';
export default async function (message) {
// このメッセージを保存します。
await db.insert(messages)
.values({ chatId: message.chat.id, text: message.text })
.run();
// このチャットのために保存したメッセージの数を数えます。
const count = await db.$count(messages, eq(messages.chatId, message.chat.id));
await api.sendMessage({
chat_id: message.chat.id,
text: `Saved. That's ${count} message(s) from this chat so far.`,
});
}
更新されたハンドラを npx tgcloud push でデプロイし、ボットにいくつかのメッセージを送信して、カウントが増加するのを確認してください。データベースは呼び出し間で永続化されます。これがボットの記憶です。
7. デプロイせずにテスト
変更を試すためにデプロイする必要はありません。npx tgcloud run は、ローカルファイルを公開せずに、プラットフォーム上でハンドラを実行します。
npx tgcloud run handlers/message '{ chat: { id: 1 }, text: