Telegram Serverless: Run Bot Backend Code Directly on Telegram Infrastructure

Telegram Serverless: Run Bot Backend Code Directly on Telegram Infrastructure

Telegram Serverless is a platform that allows developers to run backend code for Telegram bots and Mini Apps directly on Telegram's infrastructure. By utilizing a fast, isolated V8 sandbox, the platform removes the need for developers to provision servers, manage containers, or handle scaling manually.

Core Architecture and Mental Model

Telegram Serverless operates on a model where code is developed locally and synced to the cloud. The developer workflow is split across three primary environments:

  • Local Project Folder: Contains JavaScript modules, including the database schema and update handlers.
  • The Cloud: Hosts the deployed modules and the bot's persistent SQLite database.
  • tgcloud CLI: Acts as the bridge to sync local changes to the cloud.

Project Structure

A serverless project is a standard folder under version control with no build step or node_modules at runtime. It consists of three main components:

  1. handlers/: Entry points for the bot. Each file corresponds to a Telegram update type (e.g., message.js for new messages, callback_query.js for button presses). The platform routes updates to the matching handler's default export function.
  2. lib/: Shared JavaScript modules used across handlers. This directory supports subdirectories for better organization.
  3. schema.js: A single file at the project root that defines the database tables using a typed DSL.

The Database and Schema Management

Every bot receives a dedicated SQLite-backed store. The platform uses a Drizzle-like ORM for schema definition and querying, ensuring a familiar API for developers experienced with Drizzle.

Schema Definition and Migrations

Tables are defined as named exports in schema.js. The platform separates code deployment from data migration to prevent accidental data loss. The workflow is as follows:

  1. npx tgcloud push: Uploads the updated schema.js but does not modify the database.
  2. npx tgcloud migrate: Computes the difference between the schema and the live database and walks the developer through applying changes.

Migrations are categorized by risk level: Safe (additive changes), Warning (potentially destructive changes like dropping columns), and Manual (complex changes like type alterations that require raw SQL).

Database Constraints

Notably, the platform runs with PRAGMA foreign_keys turned off. Foreign keys are not supported by the DSL and will throw an error if declared. Developers must enforce referential integrity within the application logic.

The Platform SDK

At runtime, modules have access to a single library: sdk. This SDK provides three essential capabilities:

  • db: The query builder and schema DSL for interacting with the SQLite database.
  • api: A direct interface to the Telegram Bot API. It unwraps the standard response envelope, returning the result directly and throwing a BotApiError if ok: false is returned.
  • fetch: A fetch-like client for outbound HTTP requests to third-party APIs. It supports streaming for AI API responses but caps total response size at 32 MB and does not support binary payloads.

Developer Workflow and CLI

The tgcloud CLI manages the lifecycle of the bot. Key commands include:

  • login: Links the project to a bot using a CLI access token from @BotFather.
  • push: Deploys changed modules atomically. If another developer has deployed a newer revision, the push is rejected to prevent overwriting work.
  • run: Executes a handler on the platform using local files without deploying, providing a fast inner loop for testing logic.
  • webhook sync: Ensures the Telegram webhook is correctly configured to deliver only the update types for which handlers have been deployed.

Community Insights and Considerations

While the technical capabilities are extensive, community discussion on Hacker News highlighted several unanswered questions and concerns:

  • Resource Limits: Users questioned the specific quotas for execution time, storage, and bandwidth.
  • Pricing: There was significant curiosity regarding the pricing model, as the documentation does not explicitly state costs.
  • Secrets Management: Developers noted the lack of an explicit secrets storage mechanism for API keys and credentials, which are typically handled via environment variables in traditional VPS setups.
  • Accessibility: Some users reported that the "Serverless" toggle in @BotFather was not yet visible to them, suggesting a staged rollout.

Sources