Telegram Serverless
Follow on X
Home
FAQ
Apps
API
Protocol
Schema
Telegram Serverless
Telegram Serverless lets you run backend code for your bot and Mini App directly on Telegram's infrastructure — no servers to provision, no containers to keep alive, no scaling to think about. You write plain JavaScript modules, deploy them with a single command, and Telegram runs them in a fast, isolated V8 sandbox that sits right next to the Bot API and a built‑in database.
If you have ever wired a bot to a VPS, a cloud function, or a hosting panel just to answer a /start, this is the part you no longer have to do.
On this page
Why serverless
Getting started
Building with AI
On the go with BotFather
Projects & modules
The database
The SDK
CLI reference
Why serverless
A Telegram bot is, at heart, a program that reacts to updates. Traditionally you had to host that program somewhere that is always on, reachable, and secure — and then keep it that way. Telegram Serverless removes that layer entirely:
No infrastructure. There is no machine to rent, patch, or monitor. Your code runs on demand and scales with your bot automatically.
Batteries included. The Telegram Bot API, an SQLite‑backed database, and outbound HTTP are available to every module out of the box — nothing to install, no credentials to wire up.
Fast, isolated execution. Each invocation runs in a lightweight V8 isolate, close to Telegram's own systems, so calls to the Bot API and your database are quick and reliable.
A real developer workflow. A project lives in a folder on your machine under version control. You edit files, see exactly what changed, deploy atomically, and roll your database schema forward with reviewed migrations — the way you already work with everything else.
The mental model
You work in three places , and they map cleanly onto each other:
Where<br>What lives there
Your project folder<br>JavaScript modules — schema, shared code, update handlers
The cloud<br>The deployed copy of those modules, plus your bot's database
The tgcloud CLI<br>The bridge — it shows you differences and syncs them
You never SSH into anything. You edit files locally, run npx tgcloud push, and the platform takes it from there. Your bot's traffic is handled by the deployed modules; your database persists between invocations.
A project has just three kinds of code:
handlers/ # entry points — one file per Telegram update type<br>lib/ # shared code you import from anywhere<br>schema.js # your database tables<br>When an update arrives — a message, a button press, an inline query — Telegram routes it to the matching handler (handlers/message.js, handlers/callback_query.js, …) and calls its default export. That function talks to the Bot API and the database through the SDK, and returns. That is the whole loop. An update with no matching handler is simply ignored, so you add only the handlers you need.
Quick demo
Here is a complete, working demo bot. It replies to every message and remembers how many it has seen from each chat.
schema.js
import { table, integer } from 'sdk/db';
export const counters = table('counters', {<br>chatId: integer('chat_id').primaryKey(),<br>seen: integer('seen').notNull().default(0),<br>});<br>handlers/message.js
import { api, db } from 'sdk';<br>import { counters } from 'schema';<br>import { sql } from 'sdk/db';
export default async function (message) {<br>const chatId = message.chat.id;
// Insert the counter, or bump it if this chat already has one — and get the<br>// resulting row back in the same statement via .returning().<br>const [row] = await db.insert(counters)<br>.values({ chatId, seen: 1 })<br>.onConflictDoUpdate({<br>target: counters.chatId,<br>set: { seen: sql`${counters.seen} + 1` },<br>})<br>.returning()<br>.run();
await api.sendMessage({<br>chat_id: chatId,<br>text: `Hello! I've seen ${row.seen} message(s) from you.`,<br>});<br>Deploy it:
npx tgcloud push # upload the modules<br>npx tgcloud migrate # create the `counters` table<br>That's a live bot with persistent state and no server. Everything in it — api, db, the table() DSL — is described in the sections below.
Serverless is a general backend for Telegram bots and Mini Apps, not a template for one kind of app. It is ideal for:
Conversational AI Bots that need to store per‑user state in a database.
Mini App Backends that store user data and serve dynamic content.
Games and Tools — including leaderboards, quizzes and more.
Automations and Integrations that call third‑party HTTP APIs and push results into chats.
Getting started
This walkthrough takes you from an empty folder to a live bot that answers messages and stores data. It assumes you have Node.js 18 or newer installed and a bot registered with @BotFather. By the end you will have used every command you need day to day: push, migrate, run, and status.
Before anything else, switch Serverless on. In @BotFather, open your bot → Serverless and turn it on. That turns the feature on for this bot and unlocks its CLI access token, handlers, library, and database.
1....