TELEGRAM SERVERLESS · LLM-READY · OPEN
The backend,
ready to deploy.
A clean, linked mirror of Telegram’s Serverless reference—handlers, the database, the SDK, and the CLI, split into useful pieces for people and language models alike.
A snapshot of the official docs, not a live API.
THE REFERENCE, IN PIECES
Find your way around.
Search handlers, database, SDK, and CLI topics. Each entry opens its own Markdown page.
49 sections
Recent changes
Why serverless
The mental model
Quick demo
Getting started
Getting startedThis 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 e1. Create a projectThe fastest way to start is the project creator, which scaffolds a project and installs the CLI into it:2. Link your botEvery project is tied to one bot. Connect them with login, which asks for your CLI access token (@BotFather → your bot → Serverless → CLI Access → Access token — a separate token from your bot's API token) and stores it 3. Look aroundTwo commands tell you where things stand at any moment, both fully offline:4. DeploySend your modules to the cloud:5. Add a database tableLet's make the bot remember something. Open tgcloud/schema.js and declare a table:6. Store and read dataNow use the table from your handler. Edit tgcloud/handlers/message.js:7. Test without deployingYou don't have to deploy to try a change. npx tgcloud run executes a handler on the platform using your local files, without publishing them:8. Keep in syncAs you work, a handful of commands keep your local project and the cloud aligned: npx tgcloud status shows what changed, npx tgcloud push deploys, npx tgcloud pull brings your local project in line with the cloud, npx tg
Building with AI
On the go with BotFather
Projects and modules
Projects and modulesA serverless project is an ordinary folder under version control. Everything the platform runs sits in one folder, tgcloud/; the rest of the project is yours — a mini‑app front‑end, config, docs. There is no build step fAnatomy of a projectexamplebot/The module systemAt runtime, a module can see exactly two things: the platform SDK and the other modules in your project. There are no npm packages, no filesystem, and no network except through the SDK's fetch.HandlersA handler is a module in handlers/ whose default export the platform invokes when a matching update arrives.EndpointsAn endpoint is a module in endpoints/ that your Mini App calls — the place for anything the front‑end can't do on its own, like reading and writing the database, calling the Bot API, or talking to outside services with yWhat gets deployedWhen you npx tgcloud push, the CLI gathers every .js file under schema.js, lib/, handlers/, and endpoints/, and sends that exact set as your project's module space — together with the Mini App's build folder, if tgcloud.Mini App front-endThe project root is yours, and it is the natural place for your Mini App's front‑end — built with React, Vue, Svelte or plain HTML, by Vite or any other bundler. Serverless hosts its build output next to your bot. One pu
The database
The databaseEvery bot gets its own database — an SQLite‑backed store that persists between invocations and is available to every module through db. You describe your tables in schema.js with a small, typed DSL; you read and write thDeclaring tablesTables are named exports in schema.js. Calling table() builds a description at load time (it does not touch the database); the platform discovers the exported tables when you deploy schema.js and migrates the database toNo foreign keysThe runtime runs with PRAGMA foreignkeys off. A declared foreign key would be silently inert — no cascades, no orphan protection — which is worse than having none at all, so the DSL makes it impossible. Namely, .referencQueryingdb is a fluent query builder. Every query is asynchronous — the terminal methods (.all(), .get(), .values(), .run()) return Promises, so always await.MigrationsYour database changes as your bot grows. The platform keeps that safe by separating deploying code from changing data, and by classifying every schema change by how risky it is.
The SDK
The SDKAt runtime a module has one library: sdk. It bundles the three things a bot backend needs — a database, the Telegram Bot API, and outbound HTTP — with nothing to install and no credentials to configure. The database (db)The Bot APIapi gives you the entire Telegram Bot API. Call any method as api.<method>(params). Every current — and future — Bot API method works with no SDK update required.HTTPfetch is a fetch‑like client for calling the outside world — third‑party APIs, webhooks, anything over HTTP.LoggingThe standard global console is available — nothing to import, it's just there as in any JavaScript. Its output is captured and shown by npx tgcloud run, which makes it your primary debugging tool during development.
Command-line interface
Command-line interfacetgcloud is the bridge between your project folder and the cloud. It scaffolds projects, shows you what changed, deploys, runs modules, and applies database migrations. It needs Node.js 18 or newer. Two ways to get it:AuthenticationA project is tied to one bot by its token, which has the form app<id>:<secret>. The app<id> part is public and may be printed; the secret never appears in logs or errors.`init`npx tgcloud init`add`npx tgcloud add <target>`login`npx tgcloud login`status`npx tgcloud status`diff`npx tgcloud diff`push`npx tgcloud push [files...]`migrate`npx tgcloud migrate`run`npx tgcloud run <module> [args] [--ctx <json5>]`fetch`npx tgcloud fetch`pull`npx tgcloud pull`reset`npx tgcloud reset`webhook`npx tgcloud webhook`completion`tgcloud completion <bash|zsh|fish>`upgrade`npx tgcloud upgrade [--dry-run]Staying in syncEvery project has a monotonically increasing revision in the cloud, bumped on each deploy. The CLI remembers the revision it last synced with and sends it on each push. If the cloud has moved ahead — because another mach