Telegram Serverless: бот без сервера — гайд по tgcloud

Telegram Serverless — нативная среда Telegram для запуска backend-кода ботов и Mini Apps. Код исполняется по событиям в изолированных V8-средах рядом с Bot API; разработчик получает встроенную SQLite-базу, исходящий HTTP и CLI tgcloud. VPS, контейнер, ручная настройка webhook и отдельные credentials для Bot API больше не обязательны.

Практический путь состоит из восьми действий: включить Serverless в BotFather, создать проект, войти по отдельному CLI-токену, проверить diff, отправить модули через push, применить схему через migrate, протестировать handler командой run и проверить webhook. Но Telegram Serverless подходит не всем: runtime работает только с JavaScript-модулями, не поддерживает npm-пакеты и файловую систему, не даёт foreign keys, пока не умеет загружать новые файлы из handler и принимает только текстовые HTTP-ответы размером до 32 МБ.

Короткий вывод. Telegram Serverless выбирают для событийных ботов, Mini App backend, интеграций и AI-ассистентов, которые помещаются в компактный JavaScript-runtime. VPS или внешняя cloud function остаются лучше для Python, нативных зависимостей, сложной файловой обработки, собственной СУБД и задач с особыми требованиями к ресурсам.

Что такое Telegram Serverless

В классической схеме Telegram отправляет update на ваш webhook, а ваш сервер принимает событие, выполняет код и обращается к Bot API. Сервер приходится арендовать или собирать из облачных функций, защищать, обновлять, масштабировать и наблюдать.

В Telegram Serverless этот backend работает на инфраструктуре самого Telegram. По официальной документации, каждый вызов запускается в лёгком V8 isolate; рядом доступны Bot API, база на SQLite и HTTP-клиент. Разработчик хранит исходники локально и синхронизирует их с облаком через tgcloud.

Полезная модель состоит из четырёх частей: событие → модуль → данные → действие.

Telegram получает message, callback query или другой update.
Платформа вызывает соответствующий файл в handlers/.
Handler читает или меняет состояние через db.
Код отвечает через api либо вызывает внешний сервис через fetch.

Эта рамка помогает быстро проверить совместимость проекта. Если логика сводится к коротким реакциям на update и HTTP-вызовам, перенос реалистичен. Если требуется долгоживущий процесс, произвольная ОС, бинарные утилиты или сложный Python-стек, одной нативной среды будет мало.

Для каких задач подходит

Telegram называет четыре базовых класса: conversational AI bots, backend для Mini Apps, игры и инструменты, автоматизации и интеграции. На практике сюда попадают FAQ-ассистенты, лид-боты, уведомления, квизы, списки задач, личные кабинеты Mini App и связки с CRM по HTTP API.

Для AI-бота встроенная база хранит пользовательское состояние, а потоковый fetch принимает token-by-token ответ внешней модели. При проектировании корпоративного агента всё равно нужны собственные правила доступа, лимиты расходов и проверка опасных действий. Общий подход разобран в материале «ИИ-агенты в бизнесе: где есть эффект, а где хайп».

Чем он отличается от обычного serverless

Название может запутать. До появления продукта Telegram-боты уже запускали на AWS Lambda, Google Cloud Functions, Yandex Cloud Functions и Cloudflare Workers. Там serverless означает модель исполнения облачного провайдера. Здесь это отдельный нативный runtime Telegram.

Разница не только в хостинге. Платформа сама сопоставляет Telegram update с handler, выдаёт Bot API без ручной передачи bot token, предоставляет отдельную SQLite-базу на бота и управляет webhook. Внешняя функция, напротив, даёт больше языков и библиотек, но требует самостоятельно собрать интеграционный слой.

Официальная страница на 17 июля 2026 года не публикует цену, SLA, лимит CPU/RAM и максимальную длительность invocation. Поэтому обещания «бесплатно навсегда» или «подходит для любой нагрузки» не подтверждены. Эти параметры нужно проверить в BotFather и актуальных условиях перед production.

Как устроен проект

Проект состоит из трёх типов JavaScript-кода:

handlers/ # точки входа по типам Telegram update

lib/ # общий код проекта

schema.js # декларация таблиц

В облаке лежит развёрнутая копия модулей и постоянная база. Локальная папка остаётся источником кода, а CLI показывает различия и синхронизирует состояния. При полном push облачная копия зеркалит локальный набор: удалённый локально модуль будет удалён и в облаке.

Импорты задаются bare names, без ./, ../ и расширения .js:

import { api, db, fetch } from 'sdk';

import { users } from 'schema';

import { formatAnswer } from 'lib/format';

Runtime видит только sdk, его подмодули и собственные модули проекта. В нём нет npm-пакетов, файловой системы и прямой сети вне SDK fetch. Такое ограничение уменьшает поверхность исполнения, но требует заранее переписать зависимости.

Запуск первого бота за 8 шагов

Нужны Node.js 18 или новее и бот, зарегистрированный у @BotFather. CLI access token отличается от Bot API token: не путайте их и не добавляйте секреты в Git.

1. Включите Serverless

Откройте BotFather → ваш бот → Serverless и активируйте функцию. В том же разделе становятся доступны handlers, library, database и CLI Access.

2. Создайте проект

npm create @tgcloud/bot example_bot

cd example_bot

Scaffold создаёт starter handler, schema.js, пустую lib/, справочник docs/tgcloud-sdk.md, файл AGENTS.md и package.json. Существующие файлы генератор не перезаписывает.

3. Свяжите проект с ботом

Получите токен в BotFather → Serverless → CLI Access и выполните:

npx tgcloud login

Токен имеет форму app<id>:<secret> и сохраняется в git-ignored каталоге .tgcloud/. Для CI используется переменная TGCLOUD_TOKEN; CLI сначала проверяет её, затем локальные credentials.

4. Посмотрите изменения

npx tgcloud status

npx tgcloud diff

Обе команды работают офлайн, сравнивая рабочие файлы с локальной reference copy облачного состояния.

5. Разверните код

npx tgcloud push

Изменённые модули отправляются атомарным batch. Если облачная revision уже изменилась из другого места, push остановится, а не затрёт работу коллеги. Тогда используют fetch, pull или осознанный push --force.

6. Примените схему базы

npx tgcloud migrate

push никогда не меняет живую базу. Он только разворачивает новую schema.js и показывает pending changes; отдельный migrate просит подтвердить безопасные, опасные и ручные изменения.

7. Проверьте handler без deploy

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

Команда выполняет локальную версию модулей на платформе, показывает console.*, результат и длительность. Payload записывается в JSON5; сырой Update можно передать вторым контекстом через --ctx.

8. Проверьте webhook

npx tgcloud webhook

npx tgcloud webhook sync

Платформа управляет webhook и allowed_updates по набору развёрнутых handlers. Если они разошлись, sync восстанавливает соответствие; флаг --drop-pending дополнительно удаляет уже накопленные update и требует осторожности.

Как работают handlers

Каждый тип update получает отдельный файл. handlers/message.js принимает объект Message, handlers/callback_query.js — CallbackQuery. Платформа снимает внешнюю обёртку Update; оригинальный объект остаётся в ctx.update.

Минимальный echo-handler выглядит так:

import { api } from 'sdk';

export default async function (message) {

await api.sendMessage({

chat_id: message.chat.id,

text: Вы написали: ${message.text ?? '(без текста)'},

});

}

Update без соответствующего handler игнорируется. Это полезнее универсального роутера: бот получает только нужные update types, а структура проекта показывает реальные точки входа. Полный список типов предоставляет сама платформа команде add.

Встроенная база данных

Каждый бот получает отдельную постоянную SQLite-backed базу. Схема и query builder похожи на Drizzle ORM, но импортируются из sdk/db.

Пример счётчика сообщений:

// schema.js

import { table, integer } from 'sdk/db';

export const counters = table('counters', {

chatId: integer('chat_id').primaryKey(),

seen: integer('seen').notNull().default(0),

});

// handlers/message.js

import { api, db } from 'sdk';

import { counters } from 'schema';

import { sql } from 'sdk/db';

export default async function (message) {

const [row] = await db.insert(counters)

.values({ chatId: message.chat.id, seen: 1 })

.onConflictDoUpdate({

target: counters.chatId,

set: { seen: sql${counters.seen} + 1 },

})

.returning()

.run();

await api.sendMessage({

chat_id: message.chat.id,

text: Сообщений в этом чате: ${row.seen},

});

}

Поддерживаются TEXT, INTEGER, REAL, NUMERIC, BLOB и удобные boolean/json modes. Все запросы асинхронны: terminal methods возвращают Promise и требуют await.

Важное ограничение: foreign keys нет

Runtime работает с PRAGMA foreign_keys off. DSL запрещает .references() и foreignKey(), чтобы разработчик не полагался на неработающие каскады. Связи хранятся обычными id, а целостность обеспечивает прикладной код: сначала parent, затем children; при удалении — обратный порядок; orphan records проверяются отдельным запросом.

Как устроены миграции

Изменения делятся на safe, warning, manual и undocumented. Добавление таблицы или индекса обычно safe; drop требует отдельного подтверждения; смена типа колонки остаётся ручной. Для удаления поле или таблицу сначала помечают .deprecated('reason'), затем подтверждают drop в migrate.

Перед production полезен npx tgcloud migrate --dry-run. Для CI есть --safe, который автоматически применяет только безопасные изменения. --yes подтверждает и warnings, поэтому его нельзя включать без резервного сценария и review.

Bot API и внешний HTTP

Объект api предоставляет весь текущий и будущий Telegram Bot API без обновления SDK. Вызов api.sendMessage(params) использует привычные snake_case параметры и возвращает сразу result, без envelope {ok, result}.

Ошибки превращаются в BotApiError с полями code, description, method и parameters. Это позволяет отдельно обрабатывать ожидаемый 429 с retry_after, а неизвестную ошибку пробрасывать дальше.

Внешний HTTP выполняется через SDK fetch. Он поддерживает JSON, form, text, headers и потоковое чтение for await (const chunk of res.body). Последнее полезно для SSE и токенов AI API.

Ограничения HTTP точные: response должен быть текстовым, бинарные payload не поддерживаются; полный ответ ограничен 32 МБ. Потоковое чтение уменьшает расход памяти на обработку, но не увеличивает общий лимит.

Ограничения Telegram Serverless

Ограничение	Что это значит	Обходной путь
Только JavaScript-модули	Python/Go backend напрямую не переносится	оставить внешний сервис или переписать слой handlers
Нет npm packages	нельзя импортировать Express, grammY и произвольные SDK	использовать `sdk`, компактный собственный код и HTTP API
Нет filesystem	нельзя хранить временные файлы на диске	база, `file_id` Telegram или внешнее object storage
Нет foreign keys	нет каскадов и защиты от orphan rows	прикладная целостность и периодические проверки
Нет download/upload raw file bytes из handler	файловый конвейер ограничен	переиспользовать Telegram `file_id` или внешний media service
HTTP response только textual	изображения/архивы как bytes не получить	внешний сервис возвращает URL или Telegram `file_id`
HTTP response до 32 МБ	streaming не отменяет cap	пагинация, чанки, сокращение ответа
Не опубликованы цена, SLA и compute quotas	TCO и capacity нельзя посчитать по документации	проверить актуальные условия до production

Последний пункт важен для бизнеса. Отсутствие сервера в вашей панели не означает отсутствие инфраструктурных рисков. До запуска нужно узнать условия хранения данных, резервного копирования, логов, поддержки, квот и экспортируемости.

Разработка с AI-агентом

Новый проект содержит AGENTS.md и локальную справку docs/tgcloud-sdk.md. Telegram прямо проектирует scaffold так, чтобы coding agents знали специфические правила: bare imports, отсутствие foreign keys, async database calls, один handler на update type и раздельные push/migrate.

Рабочий цикл выглядит так: описать функцию естественным языком, дать агенту изменить schema.js и handlers, проверить diff, запустить tgcloud run, просмотреть logs и только затем выполнить deploy. AI не должен автоматически запускать migrate --yes или push --force: оба действия меняют внешнее состояние и требуют review.

AGENTS.md стоит обновлять вместе с проектом: перечислить доменные сущности, разрешённые внешние API, правила idempotency, формат ошибок и запретные операции. Тогда AI создаёт код в границах реальной системы, а не по общему шаблону Node.js.

Telegram Serverless vs VPS и cloud functions

Критерий	Telegram Serverless	Внешняя cloud function	VPS/контейнер
Старт	минимум инфраструктуры	нужен cloud project и webhook	ОС, deploy, TLS/webhook
Языки	JavaScript	зависит от провайдера	почти любые
Зависимости	только sdk и свой код	packages обычно доступны	полный контроль
База	встроенная SQLite-backed	внешний managed storage	любая база
Bot API credentials	встроены	bot token храните сами	bot token храните сами
Масштабирование	управляет Telegram	управляет провайдер	проектирует команда
Файлы и binaries	заметно ограничены	зависит от runtime	полный контроль
Переносимость	привязка к Telegram runtime	привязка к cloud APIs	выше при контейнерах

Выбирайте Telegram Serverless, если бот событийный, написан на JavaScript, хранит умеренное состояние и общается с внешним миром через JSON/text HTTP.

Выбирайте cloud function, если нужен другой язык или package ecosystem, но вы не хотите администрировать сервер.

Оставляйте VPS/контейнер, если нужны workers, очередь, cron, двоичные утилиты, тяжёлая обработка файлов, своя сеть, PostgreSQL, длительные задачи или строгий контроль ресурсов.

Как перенести бота с VPS

Не переносите всё одним deploy. Разделите миграцию на семь проверяемых этапов.

Инвентаризируйте update types. Составьте список message, callback_query, inline_query и других точек входа.
Разделите Telegram-слой и доменную логику. Каждый update получает handler, общая логика переезжает в lib/.
Проверьте зависимости. Для каждого npm/Python package решите: переписать, заменить SDK-вызовом, вынести во внешний HTTP service или отказаться.
Спроектируйте данные без foreign keys. Зафиксируйте порядок записи и удаления, idempotency keys и orphan checks.
Перенесите данные контролируемо. Официальная страница не описывает универсальный импорт из внешней БД, поэтому сценарий нужно подтвердить на конкретном объёме.
Прогоните handlers через run. Используйте реальные обезличенные payloads и edge cases: повтор update, 429, timeout внешнего API, пустой текст.
Переключите webhook и наблюдайте ошибки. Проверьте tgcloud webhook, pending updates и откат до старого backend.

Самый безопасный вариант — сначала вынести один некритичный handler. Если он стабильно работает, переносить остальные классы update и только потом данные.

Production-чек-лист

[ ] Serverless включён у нужного production-бота, тестовый бот отделён.
[ ] CLI token и TGCLOUD_TOKEN не попали в Git и logs.
[ ] Для каждого handler определено поведение при повторной доставке update.
[ ] Все вызовы db имеют await; batch insert разбит с учётом SQLite variable limit.
[ ] Ошибки Bot API и внешний 429 обрабатываются явно.
[ ] HTTP-ответы текстовые и гарантированно меньше 32 МБ.
[ ] File flow использует file_id или внешний media backend.
[ ] Целостность связей обеспечена без foreign keys.
[ ] Перед миграцией выполнен migrate --dry-run.
[ ] Команда знает, когда допустимы pull, reset и push --force.
[ ] Webhook показывает In sync, список allowed_updates соответствует handlers.
[ ] Отдельно подтверждены цена, квоты, SLA, backup/export и требования к данным.

FAQ

Что такое Telegram Serverless простыми словами?

Это backend внутри инфраструктуры Telegram. Вы пишете JavaScript-функции для message, callback query и других update, разворачиваете их через tgcloud, а платформа сама запускает код, управляет webhook и даёт Bot API, базу и HTTP-клиент.

Можно ли использовать Python?

Нет, официальный runtime описан для plain JavaScript modules. Python-логику можно оставить во внешнем API и вызывать через fetch, либо переписать компактный событийный слой на JavaScript.

Можно ли ставить npm-пакеты?

Нет. Runtime разрешает только platform SDK и собственные модули в schema, lib/ и handlers/. Наличие package.json нужно для локального CLI, но не превращает облачный runtime в обычный Node.js.

Нужен ли собственный webhook URL?

Нет. Платформа создаёт и синхронизирует webhook. Команда tgcloud webhook показывает URL, pending updates, последнюю ошибку и соответствие allowed_updates развёрнутым handlers.

Какая база используется?

Каждый бот получает отдельную SQLite-backed базу с Drizzle-подобной schema DSL и query builder. Данные сохраняются между invocations, но foreign keys отключены.

Можно ли сделать AI-бота со streaming?

Да, внешний fetch поддерживает потоковое чтение текстового ответа, включая SSE и token-by-token output. Нужно учитывать общий лимит 32 МБ и отдельно проектировать обновление сообщения через Bot API.

Telegram Serverless бесплатный?

В доступной официальной документации на 17 июля 2026 года цена не указана. Поэтому корректный ответ — проверить условия в BotFather и официальных материалах перед запуском, а не считать сервис бесплатным по умолчанию.

Когда Telegram Serverless не подходит?

Когда проект требует Python/Go, npm packages, filesystem, загрузку и скачивание raw files, бинарные HTTP-ответы, foreign keys, внешнюю СУБД, долгоживущие workers или подтверждённые гарантии ресурсов, которых нет в документации.

Итог

Telegram Serverless сокращает путь от BotFather до работающего backend: update сразу попадает в JavaScript-handler, состояние хранится во встроенной базе, Bot API и HTTP доступны через один SDK, а deploy выполняется одной CLI-командой. Для небольшого событийного бота это убирает VPS, контейнер, ручной webhook и отдельную операционную обвязку.

Главный компромисс — закрытый и намеренно узкий runtime. Его стоит оценивать не по обещанию «без сервера», а по рамке событие → модуль → данные → действие. Если весь сценарий помещается в неё и проходит таблицу ограничений, начните с одного handler, проверьте его через tgcloud run, затем разверните код и примените схему отдельной миграцией. Если не помещается — сохраните внешний backend и используйте Telegram Serverless только для подходящего слоя либо не переносите проект.

Источник фактов и команд: официальная документация Telegram Serverless, проверена 17 июля 2026 года.