Казалось бы, написать простого Telegram‑бота в 2 026 году — задача на один вечер. Но как только пет‑проект вырастает из «эхо‑бота» во что‑то с сохранением состояния, базой данных и тем более полноценным Telegram Mini App, начинается классическая инфраструктурная рутина: арендовать VPS, настроить веб‑сервер и SSL‑сертификаты для вебхуков, поднять базу данных, настроить деплой статики для фронтенда и следить, чтобы всё это не упало в самый неподходящий момент.

Недавно команда Telegram выкатила решение, которое закрывает все эти вопросы разом — нативную платформу Serverless (beta) прямо внутри @BotFather. Теперь запускать серверную логику бота на JavaScript, хранить данные в реляционной БД и раздавать фронтенд для Mini App можно непосредственно в облаке Telegram без собственного сервера.

В этой статье разберём, как устроен tgcloud изнутри, почему его документация идеально заточена под разработку с помощью ИИ‑агентов, и посмотрим на реальный кейс: как я поднял на этом стеке игру Wordle (wordslebot) с единым стейтом для чата и Mini App, системой друзей, лобби, мультиплеерными комнатами и внутриигровым чатом.

Что такое Telegram Serverless и что дают «из коробки»

Если открыть настройки бота в @BotFather, там появился новый раздел Serverless (beta). Идея проста: вы пишете логику на JavaScript и деплоите её в облако Telegram, где функции выполняются в быстрых изолированных V8-окружениях (V8 isolates) без необходимости поднимать собственный сервер или настраивать контейнеры.

После активации переключателя Serverless открывается панель управления из шести ключевых блоков:

• CLI Access — управление бессерверным проектом напрямую из вашего терминала.

• Handlers — функции‑обработчики, которые реагируют на различные типы обновлений (апдейтов) от Telegram.

• Endpoints — серверные функции (API‑ручки), которые может вызывать ваш Mini App.

• Library — общие модули и библиотеки, которые импортируются в ваш код.

• Database — декларативное описание таблиц и колонок базы данных прямо в коде.

• Mini App Files — хостинг фронтенд‑файлов, которые открываются у пользователей внутри Telegram.

Фактически Telegram бесплатно отдаёт разработчику полноценный Fullstack‑контур: вычислительный рантайм для бота и бэкенда, встроенную базу данных (SQLite под капотом) и CDN/хостинг статики на домене *.tgcloud.ai.

Локальная разработка, @tgcloud/cli и рай для AI‑ассистентов

Просматривать и править файлы или схему БД можно прямо в интерфейсе @BotFather, но для комфортной работы в IDE предусмотрен консольный инструмент (CLI Access). Позволяет он делать всё то же самое, что и через визуальный интерфейс, но заметно быстрее: синхронизировать файлы, запускать тесты и деплоить проект из терминала.

Развернуть новый проект можно буквально одной командой:

Bash

npm create @tgcloud/bot myproject

Для привязки локального проекта к конкретному боту используется отдельный Access token (он отличается от стандартного токена Bot API и при необходимости перевыпускается кнопкой Revoke прямо в панели).

Возможности CLI закрывают весь цикл разработки (What CLI can do):

• Добавление обработчиков (handlers) под любые типы апдейтов Telegram.

• Создание серверных эндпоинтов (endpoints) для Mini App.

• Вынесение переиспользуемого кода в общую библиотеку (library).

• Описание схемы БД и безопасное применение миграций.

• Деплой фронтенда вашего Mini App.

• Удалённый запуск любого модуля и чтение его логов прямо в консоли.

Приятный бонус для тех, кто пишет код с ИИ

Отдельного респекта заслуживает то, как команда подошла к документации (core.telegram.org/bots/serverless). Во‑первых, веб‑страница документации сразу отдаёт чистую Markdown‑версию для ботов и LLM. Во‑вторых, при инициализации проекта через npm create @tgcloud/bot в папке автоматически создаются файлы AGENTS.md и docs/tgcloud-sdk.md с полным справочником по внутреннему SDK (sdk/db, sdk/api).

Если вы используете Cursor, Claude Code или другие AI‑инструменты, модель не путает нативный SDK Telegram со сторонними библиотеками вроде telegraf или grammy — вся спецификация уже лежит в контексте проекта.

Как устроены модули: Handlers, Database и Mini App

1. Событийная модель (Handlers)

В классическом боте вы сами поднимаете HTTP‑сервер или поллинг и роутите апдейты. Здесь каждый тип события Telegram — это отдельный файл‑обработчик. Платформа сама следит за состоянием вебхука и подсвечивает статус In sync (Webhook matches your handlers), когда всё синхронизировано.

Например, для интерактивного бота достаточно активировать базовую тройку:

• message — обработка новых входящих сообщений.

• inline_query — обработка инлайн‑запросов (удобно для шаринга результатов или вызова на дуэль в любом чате).

• callback_query — реакция на нажатия инлайн‑кнопок под сообщениями.

При необходимости в один клик подключаются edited_message, stopped_message_generation, channel_post, edited_channel_post, business_connection и другие события.

2. Встроенная база данных (sdk/db) и миграции

Никаких внешних подключений, паролей и утекших .env файлов. Схема базы данных описывается прямо в коде с помощью типизированного конструктора из встроенного модуля sdk/db (table, integer, text, boolean, json, index, uniqueIndex, sql).

Причём деплой кода (npx tgcloud push) и миграция схемы БД (npx tgcloud migrate) специально разделены: если вы добавили новые таблицы или поля, панель покажет предупреждение Out of sync с числом ожидающих изменений (например, 8 changes pending), чтобы случайный пуш кода никогда не сломал продакшен‑данные.

От теории к практике: как я собрал мультиплеерный Wordle на Telegram Serverless

Когда видишь платформу, где тебе бесплатно дают рантайм, базу данных и хостинг для Mini App, сразу возникает спортивный интерес: а насколько сложную механику реально вытянуть на чистом Telegram Serverless без единого внешнего бэкенда?

Так родилась идея сделать своего Wordle‑бота (@wordslebot). Но делать очередную простую угадайку слов на 5 букв было скучно — хотелось собрать проект, где:

1. Можно играть как прямо в чате с ботом, так и в красивом Mini App с общим прогрессом.

2. Поддерживаются два языка (ru и en) со своими словарями и раскладками клавиатуры.

3. Есть полноценный социальный и мультиплеерный режим: добавление в друзья, инвайты, игровое лобби, комнаты для совместной игры и даже встроенный чат внутри комнаты.

И всё это полностью легло на архитектуру tgcloud!

Схема БД: единый стейт для чата и Mini App

Посмотрим на реальный фрагмент схемы данных из раздела Database моего бота:

За счёт того, что и чат‑обработчики (Handlers), и серверные ручки веб‑аппа (Endpoints) обращаются к одной и той же базе в sdk/db, игрок может начать угадывать слово прямо в диалоге с ботом, а продолжить раунд в Mini App — состояние attempts, targetWord и серия побед streak синхронизируются мгновенно.

Модульная архитектура (Library)

Чтобы не превращать обработчики в спагетти‑код, вся бизнес‑логика игры вынесена в раздел Library:

• lib/wordle и lib/words — ядро проверки введённых слов, подсветки букв и словарные базы.

• lib/i18n — мультиязычность интерфейса (RU / EN).

• lib/profiles и lib/growth — управление пользовательскими профилями и реферальными/виральными механиками.

• lib/friends, lib/duels и lib/rooms — логика списка друзей, быстрых дуэлей и мультиплеерных комнат.

Серверные ручки (Endpoints) и хостинг фронтенда (Mini App Files)

Самое интересное начинается на стыке Mini App и Serverless‑бэкенда. Вместо того чтобы поднимать Express/FastAPI и вручную валидировать initData от Telegram, мы просто создаём функции в разделе Endpoints:

У моего Wordle‑бота всю мультиплеерную и игровую механику обслуживают 14 эндпоинтов:

• Одиночный и соревновательный режимы: getState, daily (слово дня) и leaderboard (таблица лидеров).

• Социальные функции: friends (добавление в друзья и приглашения) и lobby (поиск и ожидание соперников).

• Жизненный цикл игровой комнаты: roomCreate, roomJoin, roomLeave, roomSet, roomStart, roomGuess, roomInfo, roomFinish и даже roomChat для общения игроков прямо во время партии.

А сам фронтенд (index.html, style.css, app.js) деплоится через tgcloud CLI напрямую в Mini App Files и сразу становится доступен по выделенному адресу вида https://app<id>.tgcloud.ai/, который остаётся только вставить в настройки Mini App бота.

Итоги: впечатления от платформы

Telegram Serverless (tgcloud) производит впечатление именно того инструмента, которого годами не хватало экосистеме ботов и Mini Apps:

1. Zero‑config инфраструктура: вы вообще не думаете про вебхуки, сертификаты, CORS, хостинг статики и настройку СУБД.

2. Честная изоляция деплоя и БД: разделение кода и миграций защищает от случайной потери данных при частых релизах.

3. Идеальная связка с ИИ: готовая документация tgcloud-sdk.md внутри шаблона проекта позволяет собирать сложные фичи (вроде комнат, чатов и друзей) в разы быстрее.

Если хотите вживую пощупать, как работает и с какой скоростью откликается Mini App и бот, полностью живущие внутри Serverless‑облака Telegram — заглядывайте протестировать мой Wordle

👉 Поиграть и протестировать бота можно здесь: @wordslebot