عصر جدید توسعه ربات‌های تلگرام: اجرای مستقیم روی زیرساخت تلگرام، بدون نیاز به سرور

برای سال‌ها، توسعه و میزبانی ربات‌های تلگرام به معنای تهیه یک سرور مجازی (VPS)، نصب محیط اجرای برنامه، پیکربندی وب‌سرور و نگهداری یک فرایند دائمی بود. توسعه‌دهندگان معمولاً مجبور بودند سرویس‌هایی مانند Nginx و ابزارهایی مانند PM2 را مدیریت کنند، فرایندهای Python یا Node.js را زنده نگه دارند و برای رفع خطاها و قطعی‌های زیرساختی وقت بگذارند.

اما اگر خود تلگرام محیطی برای اجرای کد سمت سرور ربات فراهم کند، چه اتفاقی می‌افتد؟

Telegram Serverless قابلیتی است که به توسعه‌دهندگان اجازه می‌دهد ماژول‌های JavaScript مربوط به ربات و Mini App را مستقیماً روی زیرساخت تلگرام اجرا کنند؛ بدون تهیه VPS، مدیریت سیستم‌عامل یا راه‌اندازی دستی وب‌هوک.

در این معماری، کد با ابزار رسمی tgcloud مستقر می‌شود و تلگرام اجرای Handlerها، دسترسی به Telegram Bot API، دیتابیس داخلی و درخواست‌های HTTP خروجی را مدیریت می‌کند.

مستندات رسمی: Telegram Serverless

Telegram Serverless چیست و چگونه کار می‌کند؟

ربات تلگرام در اصل برنامه‌ای است که به رویدادها پاسخ می‌دهد؛ برای مثال، دریافت پیام جدید، فشردن دکمه اینلاین یا دریافت یک Callback Query.

در معماری سنتی، توسعه‌دهنده باید برنامه را روی یک سرور میزبانی می‌کرد و دریافت Updateها را از طریق Long Polling یا Webhook مدیریت می‌کرد. در Telegram Serverless، بخش عمده این زیرساخت توسط خود تلگرام مدیریت می‌شود.

هر نوع Update به Handler مربوط به آن هدایت می‌شود. Handler منطق برنامه را اجرا می‌کند و در صورت نیاز از طریق SDK به Bot API، دیتابیس یا سرویس‌های خارجی دسترسی پیدا می‌کند.


text
کاربر در تلگرام
      │
      ▼
زیرساخت تلگرام
      │
      ▼
Handler متناسب با رویداد
      │
      ├── اجرای منطق برنامه
      ├── خواندن یا ذخیره اطلاعات
      ├── ارتباط با APIهای خارجی
      └── ارسال پاسخ به تلگرام

کد در یک محیط ایزوله مبتنی بر V8 اجرا می‌شود. هر ربات دیتابیس SQLite-backed اختصاصی خود را دارد و ماژول‌های پروژه می‌توانند از طریق SDK به Bot API، دیتابیس و قابلیت fetch برای درخواست‌های HTTP دسترسی داشته باشند.

در نتیجه، برای اجرای یک ربات معمولی دیگر لازم نیست فقط به‌منظور دریافت و پردازش پیام‌ها یک سرور همیشه‌روشن اجاره کنید. بااین‌حال، سرورلس به معنای حذف تمام زیرساخت‌ها یا تضمین رایگان بودن همه امکانات نیست؛ بلکه مدیریت محیط اجرا را به پلتفرم می‌سپارد.

مهم‌ترین قابلیت‌های Telegram Serverless

۱. اجرای کد ربات روی زیرساخت خود تلگرام

مهم‌ترین تفاوت Telegram Serverless با سرویس‌های عمومی سرورلس مانند AWS Lambda یا Cloudflare Workers، محل اجرای کد است. در این حالت، کد Backend ربات روی زیرساخت تلگرام اجرا می‌شود و لازم نیست برای میزبانی وب‌هوک، یک سرویس جداگانه انتخاب کنید یا URL وب‌هوک را دستی مدیریت کنید.

تلگرام Updateها را براساس Handlerهای مستقرشده مسیریابی می‌کند. هر Handler در یک فایل JavaScript داخل پوشه tgcloud/handlers/ قرار می‌گیرد و تابع export default آن هنگام دریافت Update مربوط اجرا می‌شود.

این ساختار تعداد اجزای زیرساختی پروژه را کاهش می‌دهد و فرایند توسعه و نگهداری را ساده‌تر می‌کند.

۲. مقیاس‌پذیری بدون مدیریت دستی سرور

در میزبانی سنتی، توسعه‌دهنده باید فرایندهای برنامه و منابع سرور را مدیریت کند و برای افزایش ترافیک، ظرفیت بیشتری فراهم کند. Telegram Serverless مدیریت اجرای رویدادها را به پلتفرم می‌سپارد تا توسعه‌دهنده بیشتر روی منطق ربات تمرکز کند.

بااین‌حال، مقیاس‌پذیری خودکار به معنای ظرفیت نامحدود نیست. محدودیت‌های سرویس، Bot API، دیتابیس و سرویس‌های خارجی همچنان باید در طراحی برنامه لحاظ شوند.

۳. دسترسی داخلی به Telegram Bot API

این پلتفرم SDK اختصاصی خود را دارد. به‌جای ساخت دستی درخواست HTTP به api.telegram.org، می‌توان از ماژول api استفاده کرد.

برای نمونه، کد زیر یک Handler ساده برای پیام‌های جدید است:


javascript
// tgcloud/handlers/message.js
import { api } from 'sdk';

export default async function (message) {
  await api.sendMessage({
    chat_id: message.chat.id,
    text: `You said: ${message.text ?? '(no text)'}`,
  });
}

Handler، محتوای مربوط به Update را به‌عنوان آرگومان اول دریافت می‌کند. برای handlers/message.js این آرگومان همان Message است، نه شیء کامل Update. آرگومان دوم نیز یک شیء context به نام ctx است که اطلاعات تکمیلی، از جمله Update خام، را در اختیار کد قرار می‌دهد.

۴. دیتابیس داخلی مبتنی بر SQLite

ربات‌ها معمولاً به ذخیره اطلاعات کاربران، تنظیمات، وضعیت مکالمه یا داده‌های برنامه نیاز دارند. Telegram Serverless برای هر ربات یک دیتابیس مبتنی بر SQLite فراهم می‌کند که بین فراخوانی‌ها پایدار می‌ماند.

ساختار جدول‌ها در tgcloud/schema.js تعریف می‌شود و عملیات دیتابیس از طریق ماژول sdk/db انجام می‌گیرد.

برای مثال:


javascript
// 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),
});

این Schema جدولی برای نگهداری شمارنده پیام هر چت تعریف می‌کند. پس از تغییر Schema، باید کد را منتشر کنید و سپس Migration را جداگانه اعمال کنید:


bash
npx tgcloud push
npx tgcloud migrate

تفکیک انتشار کد از تغییر دیتابیس کمک می‌کند که یک Deploy معمولی، بدون تأیید توسعه‌دهنده، ساختار دیتابیس را تغییر ندهد.

نکته فنی: در محیط فعلی مستندات Telegram Serverless، Foreign Keyهای SQLite پشتیبانی نمی‌شوند. روابط بین جدول‌ها باید با طراحی مناسب و اعتبارسنجی در منطق برنامه مدیریت شوند.

۵. ارتباط HTTP با سرویس‌های خارجی

Telegram Serverless به قابلیت‌های داخلی تلگرام محدود نیست. ماژول fetch امکان ارسال درخواست HTTP به APIهای خارجی را فراهم می‌کند.


javascript
import { fetch } from 'sdk';

export default async function () {
  const response = await fetch('https://api.example.com/data');

  if (!response.ok) {
    throw new Error(response.statusText);
  }

  const data = await response.json();
  console.log(data);
}

این قابلیت برای اتصال به سرویس‌های هوش مصنوعی، دریافت اطلاعات از APIهای دیگر یا یکپارچه‌سازی با سامانه‌های خارجی مفید است. البته محدودیت‌های شبکه و سرویس خارجی، از جمله تأخیر و نرخ درخواست، همچنان برقرار هستند.

چگونه اولین ربات خود را با Telegram Serverless بسازیم؟

برای شروع، طبق مستندات رسمی به Node.js نسخه ۱۸ یا جدیدتر و یک ربات ثبت‌شده از طریق @BotFather نیاز دارید.

مرحله اول: فعال‌کردن Serverless

در @BotFather ربات موردنظر را باز کنید، وارد بخش Serverless شوید و این قابلیت را فعال کنید. این کار دسترسی CLI، Handlerها، کتابخانه مشترک و دیتابیس ربات را فعال می‌کند.

مرحله دوم: ساخت پروژه

در ترمینال دستورهای زیر را اجرا کنید:


bash
npm create @tgcloud/bot example_bot
cd example_bot

این دستور ساختار اولیه پروژه را ایجاد می‌کند و CLI را به‌عنوان وابستگی توسعه نصب می‌کند. ساختار اصلی پروژه به این شکل است:


text
example_bot/
├── tgcloud/
│   ├── handlers/
│   │   └── message.js
│   ├── lib/
│   └── schema.js
├── docs/
│   └── tgcloud-sdk.md
├── AGENTS.md
├── package.json
└── tgcloud.jsonc

پوشه tgcloud/ شامل ماژول‌هایی است که روی پلتفرم اجرا می‌شوند. handlers/ برای Updateهای تلگرام، lib/ برای کدهای مشترک و schema.js برای تعریف جدول‌های دیتابیس است. اگر پروژه Mini App داشته باشد، پوشه endpoints/ نیز برای توابع Backend آن استفاده می‌شود.

مرحله سوم: اتصال پروژه به ربات


bash
npx tgcloud login

CLI از شما یک CLI access token می‌خواهد. این توکن از مسیر زیر در @BotFather قابل دریافت است:

Your Bot → Serverless → CLI Access → Access token

این توکن با Bot API Token متفاوت است. اطلاعات ورود در پوشه محلی .tgcloud/ ذخیره می‌شوند؛ بنابراین این پوشه را در مخزن عمومی Git قرار ندهید و اطلاعات محرمانه آن را منتشر نکنید.

مرحله چهارم: استقرار کد


bash
npx tgcloud push

این دستور ماژول‌های تغییرکرده را در یک بسته اتمیک منتشر می‌کند. پس از Deploy، ربات را در تلگرام باز کنید و پیام بفرستید تا Handler مربوط را آزمایش کنید.

برای بررسی وضعیت و تفاوت‌های فایل‌های محلی با نسخه مستقرشده، از این دستورها استفاده کنید:


bash
npx tgcloud status
npx tgcloud diff

مرحله پنجم: آزمایش بدون استقرار

برای اجرای آزمایشی یک Handler با کد محلی، بدون انتشار نسخه جدید، می‌توان از دستور run استفاده کرد:


bash
npx tgcloud run handlers/message '{ chat: { id: 1 }, text: "hello" }'

این دستور Handler را روی پلتفرم با ورودی آزمایشی اجرا می‌کند و خروجی console و مدت زمان اجرا را نمایش می‌دهد. این روش برای عیب‌یابی و توسعه سریع مفید است.

مرحله ششم: اعمال تغییرات دیتابیس

اگر Schema دیتابیس را تغییر داده‌اید، ابتدا آن را منتشر کنید و سپس Migration را اجرا کنید:


bash
npx tgcloud push
npx tgcloud migrate

فرمان migrate تغییرات پیشنهادی را نمایش می‌دهد و برای اعمال آن‌ها تأیید می‌گیرد. به این ترتیب تغییر ساختار دیتابیس از انتشار عادی کد جدا می‌ماند.

توسعه با هوش مصنوعی

پروژه‌هایی که با npm create @tgcloud/bot ساخته می‌شوند، فایل AGENTS.md و مستندات SDK را نیز دارند. این فایل‌ها می‌توانند به ابزارهای کدنویسی هوش مصنوعی کمک کنند تا ساختار پروژه و قواعد خاص این Runtime را بهتر بشناسند.

برای نمونه، می‌توانید پروژه را بسازید و سپس با ابزاری مانند Cursor یا Claude Code از دستیار بخواهید Handlerها و Schema لازم برای یک قابلیت را ایجاد کند. بااین‌حال، کد تولیدشده باید بازبینی و آزمایش شود؛ به‌ویژه چون Runtime پکیج‌های دلخواه npm، دسترسی مستقیم به فایل‌سیستم و شبکه عمومی خارج از SDK را در اختیار ماژول‌ها قرار نمی‌دهد.

چرخه توسعه پیشنهادی:


bash
npm create @tgcloud/bot my-bot
cd my-bot
npx tgcloud run handlers/message '{ chat: { id: 1 }, text: "hello" }'
npx tgcloud push

در صورت تغییر Schema، پس از انتشار کد، npx tgcloud migrate را نیز اجرا کنید.

میزبانی Telegram Mini App

طبق تغییرات مستندات در ۶ اکتبر ۲۰۲۶، Telegram Serverless از استقرار Frontend مربوط به Mini App در کنار Backend پشتیبانی می‌کند. فایل‌های خروجی Build می‌توانند هم‌زمان با ماژول‌های ربات منتشر شوند.

آدرس Mini App از الگوی زیر پیروی می‌کند؛ آدرس نهایی را خود CLI هنگام استقرار اعلام می‌کند:


text
https://app<app_id>.tgcloud.ai/

برای افزودن Serverless به یک پروژه Frontend موجود، می‌توانید در پوشه پروژه دستورات زیر را اجرا کنید:


bash
npm create vite@latest example_app
cd example_app
npm create @tgcloud/bot .

پروژه‌ساز فایل‌های فعلی را بازنویسی نمی‌کند و پوشه tgcloud/ را کنار Frontend اضافه می‌کند. تنظیمات Build و استقرار در tgcloud.jsonc قابل مدیریت است.

ارتباط Frontend با Backend

توابع Backend مربوط به Mini App داخل پوشه tgcloud/endpoints/ قرار می‌گیرند. از سمت Mini App می‌توان یک Endpoint را با Telegram.WebApp.Serverless.call فراخوانی کرد:


javascript
Telegram.WebApp.Serverless.call('getProfile', { lang: 'en' }, function (err, profile) {
  if (err) {
    console.error(err);
    return;
  }

  console.log(profile);
});

پلتفرم اطلاعات اولیه Mini App را بررسی می‌کند و اطلاعات کاربر را از طریق context در اختیار Endpoint می‌گذارد. بااین‌حال، برنامه همچنان باید ورودی‌ها را اعتبارسنجی کند و مجوز دسترسی به عملیات حساس را خودش بررسی کند.

محدودیت‌ها و نکاتی که باید بدانید

۱. Runtime مبتنی بر JavaScript است

Backend این پلتفرم با ماژول‌های JavaScript اجرا می‌شود. بنابراین برنامه‌ای که با Python و کتابخانه‌هایی مانند Pyrogram نوشته شده، بدون بازنویسی مستقیماً روی این محیط اجرا نمی‌شود.

۲. پکیج‌های دلخواه npm در Runtime قابل استفاده نیستند

در زمان اجرا، ماژول‌ها به SDK پلتفرم و سایر فایل‌های پروژه داخل tgcloud/ دسترسی دارند. دسترسی مستقیم به فایل‌سیستم وجود ندارد و درخواست‌های شبکه باید از طریق fetch ارائه‌شده توسط SDK انجام شوند. در نتیجه، پکیج‌هایی که به محیط کامل Node.js یا وابستگی‌های Native نیاز دارند، لزوماً قابل استفاده نیستند.

۳. طراحی دیتابیس همچنان مهم است

دیتابیس داخلی برای بسیاری از ربات‌ها کافی است؛ بااین‌حال، باید Schema مناسب، کوئری‌های کارآمد و مدیریت صحیح روابط داده‌ها را در نظر بگیرید. به‌ویژه، Foreign Keyها در این محیط پشتیبانی نمی‌شوند.

۴. هزینه و محدودیت‌های حساب را بررسی کنید

مستندات فنی ویژگی‌ها و روش استفاده را توضیح می‌دهند، اما پیش از استفاده تجاری یا پرترافیک باید شرایط سرویس، دسترسی حساب و هرگونه سهمیه یا هزینه اعلام‌شده را بررسی کنید. رایگان بودن تمام اجزای یک پروژه را نباید بدون منبع رسمی فرض کرد.

۵. انتشار کد و Migration دو مرحله جدا هستند

npx tgcloud push کد را منتشر می‌کند؛ تغییرات ساختار دیتابیس تنها با Migration اعمال می‌شوند. این جداسازی از تغییر ناخواسته ساختار داده در Deployهای معمولی جلوگیری می‌کند.

Telegram Serverless برای چه پروژه‌هایی مناسب است؟

این معماری می‌تواند برای پروژه‌های زیر گزینه مناسبی باشد:

ربات‌های مکالمه‌ای و پشتیبانی کاربران
ربات‌های هوش مصنوعی با نیاز به نگهداری وضعیت کاربران
بازی‌ها، آزمون‌ها، لیدربوردها و ابزارهای تعاملی
ربات‌های اطلاع‌رسانی و اتصال به APIهای خارجی
Telegram Mini Appهایی که به Backend و ذخیره‌سازی داده نیاز دارند
ابزارهای مدیریتی و اتوماسیون‌های تلگرامی

در مقابل، پروژه‌هایی که به اجرای دائمی پردازش‌ها، محیط کامل Python یا Node.js، وابستگی‌های Native یا دسترسی مستقیم به سیستم‌عامل نیاز دارند، ممکن است همچنان به VPS یا معماری ترکیبی احتیاج داشته باشند.

جمع‌بندی: تمرکز بیشتر بر محصول، نه مدیریت سرور

Telegram Serverless روش متفاوتی برای توسعه ربات‌ها ارائه می‌کند: به‌جای تهیه و نگهداری زیرساخت مستقل، توسعه‌دهنده می‌تواند ماژول‌های JavaScript را با ابزار رسمی tgcloud روی زیرساخت تلگرام مستقر کند.

ترکیب Handlerهای رویدادمحور، دسترسی داخلی به Bot API، دیتابیس SQLite، درخواست‌های HTTP خروجی و میزبانی Mini App، این قابلیت را به گزینه‌ای قابل‌توجه برای نسل جدید برنامه‌های تلگرامی تبدیل می‌کند.

این راهکار برای همه پروژه‌ها مناسب نیست؛ به‌ویژه اگر برنامه فعلی به Python، Pyrogram یا فرایندهای دائمی وابسته باشد. محدودیت‌های Runtime، طراحی دیتابیس و شرایط استفاده سرویس باید پیش از مهاجرت بررسی شوند.

Telegram Serverless به معنی حذف تمام زیرساخت‌ها نیست؛ به معنی واگذاری بخش بزرگی از مدیریت زیرساخت به تلگرام است.

منابع رسمی

A New Era in Telegram Bot Development: Run Bots Directly on Telegram's Infrastructure

For years, developing and hosting Telegram bots meant provisioning a Virtual Private Server (VPS), installing a runtime, configuring a web server, and keeping an application process running continuously. Developers often had to manage tools such as Nginx and PM2, keep Python or Node.js processes alive, and troubleshoot infrastructure failures and unexpected downtime.

But what if Telegram itself provided an environment for running a bot's backend?

Telegram Serverless lets developers run JavaScript modules for bots and Mini Apps directly on Telegram's infrastructure — without provisioning a VPS, managing an operating system, or manually configuring a webhook endpoint.

Developers deploy their code with the official tgcloud CLI. Telegram manages handler execution, access to the Telegram Bot API, a built-in database, and outbound HTTP requests.

Official documentation: Telegram Serverless

What Is Telegram Serverless, and How Does It Work?

A Telegram bot is fundamentally a program that reacts to events, such as incoming messages, inline button presses, and callback queries.

In a traditional architecture, developers had to host the application on a server and manage update delivery through Long Polling or webhooks. Telegram Serverless moves much of this infrastructure management to Telegram itself.

Each update type is routed to its corresponding handler. The handler executes application logic and, when needed, uses the SDK to access the Bot API, database, or external services.


text
Telegram User
      │
      ▼
Telegram Infrastructure
      │
      ▼
Matching Update Handler
      │
      ├── Run application logic
      ├── Read or write data
      ├── Call external APIs
      └── Send a response through Telegram

Code runs in an isolated V8-based environment. Each bot has its own SQLite-backed database, and project modules can use the SDK to access the Bot API, database, and fetch for outbound HTTP requests.

As a result, an ordinary bot no longer needs an always-on server just to receive and process messages. However, serverless does not remove every component of infrastructure or guarantee that every feature is free; it shifts runtime management to the platform.

Key Features of Telegram Serverless

1. Run Bot Code on Telegram's Own Infrastructure

The most important difference between Telegram Serverless and general-purpose services such as AWS Lambda or Cloudflare Workers is where the code runs. With Telegram Serverless, the bot's backend executes on Telegram's infrastructure, so you do not need to choose a separate provider to host a webhook or manage the webhook URL manually.

Telegram routes updates according to the handlers you deploy. Each handler is a JavaScript file inside tgcloud/handlers/, and its export default function is invoked when a matching update arrives.

This reduces infrastructure components and simplifies development and maintenance.

2. Scaling Without Manually Managing Servers

With traditional hosting, developers manage application processes and server resources, and must prepare additional capacity when traffic grows. Telegram Serverless delegates execution management to the platform so developers can focus on bot logic.

Automatic scaling does not mean unlimited capacity, however. Service limits, Bot API restrictions, database constraints, and external service quotas still need to be considered.

3. Built-in Access to the Telegram Bot API

The platform provides a dedicated SDK. Instead of manually constructing HTTP requests to api.telegram.org, developers can use the api module.

For example, the following is a simple handler for incoming messages:


javascript
// tgcloud/handlers/message.js
import { api } from 'sdk';

export default async function (message) {
  await api.sendMessage({
    chat_id: message.chat.id,
    text: `You said: ${message.text ?? '(no text)'}`,
  });
}

A handler receives the relevant update payload as its first argument. For handlers/message.js, that argument is the Message object, not the complete Update. The second argument is a context object named ctx, which includes additional information such as the raw update.

4. Built-in SQLite-Backed Database

Bots often need to store user information, settings, conversation state, or application data. Telegram Serverless provides each bot with a SQLite-backed database that persists between invocations.

Tables are declared in tgcloud/schema.js, and database operations use the sdk/db module.

For example:


javascript
// 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),
});

This schema defines a table for tracking a message counter for each chat. After changing the schema, deploy the code and apply the migration separately:


bash
npx tgcloud push
npx tgcloud migrate

Separating code deployment from database changes ensures that an ordinary deployment does not modify the database schema without the developer's confirmation.

Technical note: The current Telegram Serverless environment does not support SQLite foreign keys. Relationships between tables must be handled through application logic and appropriate data validation.

5. HTTP Requests to External Services

Telegram Serverless is not limited to Telegram's built-in functionality. The fetch module supports outbound HTTP requests to external APIs.


javascript
import { fetch } from 'sdk';

export default async function () {
  const response = await fetch('https://api.example.com/data');

  if (!response.ok) {
    throw new Error(response.statusText);
  }

  const data = await response.json();
  console.log(data);
}

This is useful for integrating AI services, retrieving data from other APIs, and connecting to external systems. Network and third-party service constraints, including latency and rate limits, still apply.

How to Build Your First Telegram Serverless Bot

According to the official documentation, getting started requires Node.js version 18 or newer and a bot registered through @BotFather.

Step 1: Enable Serverless

Open your bot in @BotFather, navigate to Serverless, and enable the feature. This unlocks the bot's CLI access, handlers, shared library, and database.

Step 2: Create a Project

Run the following commands in your terminal:


bash
npm create @tgcloud/bot example_bot
cd example_bot

The project creator scaffolds the initial structure and installs the CLI as a development dependency. A typical project looks like this:


text
example_bot/
├── tgcloud/
│   ├── handlers/
│   │   └── message.js
│   ├── lib/
│   └── schema.js
├── docs/
│   └── tgcloud-sdk.md
├── AGENTS.md
├── package.json
└── tgcloud.jsonc

The tgcloud/ directory contains the modules executed by the platform. handlers/ processes Telegram updates, lib/ contains shared code, and schema.js defines database tables. For a Mini App, the endpoints/ directory contains its backend functions.

Step 3: Link the Project to Your Bot


bash
npx tgcloud login

The CLI asks for a CLI access token, available in this path in @BotFather:

Your Bot → Serverless → CLI Access → Access token

This token is different from the Bot API token. Login data is stored in the local .tgcloud/ directory, so do not include this directory in a public Git repository or expose its secrets.

Step 4: Deploy the Code


bash
npx tgcloud push

This command deploys the changed modules in an atomic batch. After deployment, open the bot in Telegram and send it a message to test the relevant handler.

Use these commands to inspect the state of your local project and its differences from the deployed version:


bash
npx tgcloud status
npx tgcloud diff

Step 5: Test Without Deploying

To run a handler using your local code without publishing a new deployment, use run:


bash
npx tgcloud run handlers/message '{ chat: { id: 1 }, text: "hello" }'

This command executes the handler on the platform with test input and displays console output and execution time. It is useful for debugging and rapid development.

Step 6: Apply Database Changes

If you modify the database schema, deploy it and then run the migration:


bash
npx tgcloud push
npx tgcloud migrate

The migrate command presents the proposed changes and asks for confirmation before applying them. This keeps schema changes separate from regular code deployments.

Building with AI

Projects created with npm create @tgcloud/bot also include AGENTS.md and SDK documentation. These files help AI coding tools understand the project structure and the conventions of this runtime.

For example, you can scaffold a project and then use a tool such as Cursor or Claude Code to help create handlers and schema for a feature. Generated code must still be reviewed and tested, especially because the runtime does not support arbitrary npm packages, direct filesystem access, or general network access outside the SDK.

A suggested development loop is:


bash
npm create @tgcloud/bot my-bot
cd my-bot
npx tgcloud run handlers/message '{ chat: { id: 1 }, text: "hello" }'
npx tgcloud push

If you change the schema, also run npx tgcloud migrate after deploying the code.

Hosting a Telegram Mini App

According to the documentation update dated October 6, 2026, Telegram Serverless supports deploying a Mini App's frontend alongside its backend. The frontend build output can be deployed together with the bot's modules.

The Mini App URL follows this pattern; the CLI prints the exact URL after deployment:


text
https://app<app_id>.tgcloud.ai/

To add Serverless to an existing frontend project, you can run these commands from the project directory:


bash
npm create vite@latest example_app
cd example_app
npm create @tgcloud/bot .

The project creator does not overwrite existing files. It adds tgcloud/ next to the frontend, and build and deployment settings can be managed in tgcloud.jsonc.

Connecting the Frontend to the Backend

Mini App backend functions live in tgcloud/endpoints/. The frontend can call an endpoint through Telegram.WebApp.Serverless.call:


javascript
Telegram.WebApp.Serverless.call('getProfile', { lang: 'en' }, function (err, profile) {
  if (err) {
    console.error(err);
    return;
  }

  console.log(profile);
});

The platform validates the Mini App's initialization data and provides the user information to the endpoint through its context. However, the application must still validate inputs and enforce authorization for sensitive operations.

Limitations and Important Considerations

1. The Runtime Uses JavaScript

The backend runs JavaScript modules. Applications written in Python using libraries such as Pyrogram cannot run in this environment without rewriting their backend logic.

2. Arbitrary npm Packages Are Not Available at Runtime

At runtime, modules can access the platform SDK and other project files inside tgcloud/. Direct filesystem access is unavailable, and network requests must use the SDK's fetch. Consequently, packages that depend on the full Node.js environment or native dependencies may not work.

3. Database Design Still Matters

The built-in database may be enough for many bots, but good schema design, efficient queries, and correct handling of relationships are still essential. Foreign keys are not supported in this environment.

4. Check Pricing and Account Limits

The technical documentation describes features and usage, but before a commercial or high-traffic deployment, check the service conditions, account access, and any published usage quotas or charges. Do not assume that every part of a project is free without an official source.

5. Code Deployment and Migrations Are Separate

npx tgcloud push deploys code; database schema changes are applied through migrations. This separation helps prevent unintended schema changes during routine deployments.

Which Projects Benefit from Telegram Serverless?

This architecture may be a good fit for:

Conversational and customer-support bots
AI-powered bots that store user state
Games, quizzes, leaderboards, and interactive tools
Notification bots and external API integrations
Telegram Mini Apps that need backend logic and persistent storage
Administrative tools and Telegram automations

Applications that require continuously running processes, a full Python or Node.js environment, native dependencies, or direct operating-system access may still need a VPS or a hybrid architecture.

Conclusion: Focus on the Product, Not Server Management

Telegram Serverless offers a different approach to bot development. Instead of provisioning and maintaining separate infrastructure, developers can deploy JavaScript modules to Telegram's infrastructure using the official tgcloud CLI.

The combination of event handlers, built-in Bot API access, an SQLite-backed database, outbound HTTP requests, and Mini App hosting makes it a compelling option for a new generation of Telegram applications.

It is not suitable for every project, especially applications that depend on Python, Pyrogram, or continuously running processes. Runtime limitations, database design, and service conditions should be reviewed before migrating.

Telegram Serverless does not eliminate all infrastructure; it delegates much of that infrastructure management to Telegram.