Telegram Serverless: как запустить бота без сервера

Что такое Telegram Serverless

Telegram Serverless — среда, в которой код бота и бэкенда Mini App выполняется на инфраструктуре Telegram. Вы пишете модули на JavaScript, отправляете их одной командой, и Telegram запускает их в изолированной песочнице V8 рядом с Bot API и встроенной базой.

Раньше даже эхо-боту нужен был компьютер, который всегда онлайн: VPS, Docker, панель хостинга или облачная функция. Serverless убирает этот слой для узкого класса задач. Пришло обновление — вызвался файл-обработчик — он ответил через API — процесс закончился.

В проекте три места, и они совпадают между собой:

• Папка на компьютере — JavaScript-модули под git
• Облако Telegram — задеплоенная копия плюс база бота
• CLI tgcloud — мост: показывает разницу и синхронизирует

SSH никуда не нужен. Webhook платформа ведёт сама: вы не указываете URL своего сервера. База переживает отдельные вызовы, хотя сам обработчик живёт коротко.

Зачем Telegram это сделал

Большая часть ботов в документации — программы, которые реагируют на апдейт. Сообщение, нажатие кнопки, inline-запрос. Для этого не обязателен сервер, который крутится сутками и ждёт getUpdates.

По словам Telegram, у среды четыре свойства:

• Нет своей инфраструктуры. Не арендуете машину, не патчите систему, не следите за диском.
• Сразу есть Bot API, SQLite и исходящий HTTP. Ставить пакеты и прописывать секреты API не нужно.
• Изолированный V8. Каждый вызов — отдельная песочница рядом с системами Telegram.
• Привычный цикл разработчика. Файлы, git, атомарный деплой, миграции схемы отдельно от кода.

Это инструмент программиста. С телефона можно править файлы в BotFather, с компьютера — через CLI. Конструктора «кнопками без кода» здесь нет. ИИ в экосистеме Serverless — файлы AGENTS.md и docs/tgcloud-sdk.md для Cursor, Claude Code и похожих агентов: ассистент пишет JS, человек проверяет и пушит.

Как устроен проект: handlers, lib, schema

После npm create @tgcloud/bot папка выглядит так:

my-bot/
├─ docs/
│  └─ tgcloud-sdk.md
├─ handlers/
│  └─ message.js
├─ lib/
├─ AGENTS.md
├─ package.json
└─ schema.js

В облако уходят только schema.js и .js из handlers/ и lib/. Markdown, конфиги и папка .tgcloud/ остаются у вас.

Обработчики: один файл на тип апдейта

Платформа смотрит на имя файла. Пришло сообщение — вызывается handlers/message.js. Нажали кнопку — handlers/callback_query.js. Inline — handlers/inline_query.js. Подкаталогов в handlers/ нет.

Если файла нет или он пустой, апдейт этого типа игнорируется. Держите только нужные обработчики: лишний файл — лишний запуск кода.

Функция по умолчанию получает уже «развёрнутый» объект: в message.js это Message, не весь Update. Второй аргумент — ctx, там сырой ctx.update, если нужен update_id.

lib/ и schema.js

В lib/ кладут общее: форматирование, работа с таблицами, запросы к внешнему API. Подпапки разрешены, например lib/internal/util.js. Сама платформа эти файлы не вызывает — их импортируют обработчики.

schema.js в корне описывает таблицы. Задеплоить схему и применить её к базе — разные шаги. push код заливает, migrate меняет таблицы. Случайно снести данные деплоем нельзя.

Импорты: только голые имена

В рантайме модуль видит SDK и другие модули проекта. npm, файловая система и относительные пути ./schema не работают. Пишут так:

import { users } from 'schema';
import { addItem } from 'lib/cart';
import { db, api, fetch } from 'sdk';

Расширение .js в импорте тоже ломает сборку. Это частая ошибка, если копировать привычку из Node.

Что Serverless хорошо закрывает

Для простого бота среды хватает. Человек нажал Start — бот поздоровался, запомнил chat id в SQLite, ответил на текст. Счётчик сообщений, туду-лист, викторина, таблица лидеров, бэкенд Mini App, который кладёт данные пользователя в базу, — это как раз тот контур, который описан в доке Telegram.

Типичные сценарии:

• Ответ на /start и несколько команд
• FAQ из заранее известных фраз
• Состояние пользователя в SQLite: список дел, прогресс квиза
• Кнопки callback и правка сообщения
• Запрос к внешнему HTTP API через fetch и ответ в чат
• Бэкенд Mini App без своего сервера

Если задача — «пусть бот живёт и отвечает», Serverless снимает аренду VPS. Если задача — магазин, курс с оплатой, рассылка по расписанию, разбор фото или готовый бот без Cursor, этой среды уже мало. Об этом ниже, после настройки.

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

Песочница специально узкая: так модули быстро грузятся и безопаснее исполняются. Перед тем как переносить магазин или ИИ-бота, посмотрите на потолок.

Исходящий HTTP есть: можно дернуть платёжный шлюз или модель ИИ. Но крутить тяжёлую обработку медиа, ставить pip-зависимости и держать бота «всегда включённым» платформа не обещает. Тарифы, квоты CPU и размер базы в публичной доке на сентябрь 2026 не указаны — это стоит закладывать как риск для продакшена.

Как включить Telegram Serverless в BotFather

Без этого шага CLI не привяжется к боту.

С этого момента тот же проект можно править с телефона в BotFather: хендлеры, lib/, schema.js, прогон обработчика с выводом console.

Как создать проект и задеплоить бота через tgcloud

Нужен Node.js 18 или новее. CLI ставят вместе с проектом, глобально ставить не обязательно.

1. Скаффолд

npm create @tgcloud/bot my-bot
cd my-bot

Аргумент — папка. Точка . скаффолдит в текущую. Существующие файлы создатель не затирает. CLI окажется локальной dev-зависимостью, команды запускают через npx tgcloud … или npm-скрипты вроде npm run deploy.

Глобально: npm install -g @tgcloud/cli, затем tgcloud init. Глобальная установка нужна ещё и для tab-completion в shell.

2. Логин

npx tgcloud login

Вставьте CLI-токен. Для CI токен дают переменной TGCLOUD_TOKEN, на диск его тогда не пишут. Команды посреди работы токен не спрашивают: нет терминала — нет зависания в пайплайне.

3. Посмотреть состояние

npx tgcloud status
npx tgcloud diff

Обе команды офлайн: сравнивают папку с локальным снимком в .tgcloud/. Сразу после init всё новое, в облаке ещё пусто.

4. Деплой

npx tgcloud push

Заливается атомарный набор модулей. Удалённый локально файл пропадёт и в облаке. После push стартовый handlers/message.js уже отвечает в Telegram — обычно эхом текста. Базу push не меняет, даже если вы правили schema.js.

5. Прогон без публикации

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

Выполняется облачный рантайм, но файлы берутся с вашего диска. В ответ — логи console.*, возвращаемое значение и время. Payload — JSON5, кавычки у ключей можно не ставить. Контекст вторым аргументом: --ctx '{ update: { update_id: 1 } }'.

Пример: бот, который отвечает на /start

Стартовый обработчик из скаффолда обычно повторяет текст. Ниже — явный ответ на команду Start и эхо остального. Это тот объём, под который Serverless заточен.

import { api } from 'sdk';

export default async function (message) {
  const chatId = message.chat.id;
  const text = message.text ?? '';

  if (text === '/start') {
    await api.sendMessage({
      chat_id: chatId,
      text: 'Привет! Я простой serverless-бот. Напишите что-нибудь — повторю.',
    });
    return;
  }

  await api.sendMessage({
    chat_id: chatId,
    text: `Вы написали: ${text || '(нет текста)'}`,
  });
}

Параметры Bot API — в snake_case, как в документации: chat_id, reply_markup. Обёртку { ok: true, result } SDK снимает сам: api.getMe() сразу отдаёт объект пользователя. Ошибка API бросает BotApiError с полями code, description, method, parameters.

Залейте файл и откройте бота:

npx tgcloud push

Если после добавления нового типа апдейта сообщения не доходят, проверьте webhook: npx tgcloud webhook и при необходимости npx tgcloud webhook sync. Платформа сама держит URL, но список allowed_updates должен совпасть с файлами в handlers/.

Как добавить базу SQLite

У каждого бота своя база. DSL и построитель запросов близки к Drizzle ORM: table(), select().from().where(), onConflictDoUpdate, тег sql. Импорт — из sdk/db. Каждый запрос асинхронный, терминальные методы нужно await.

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

export const counters = table('counters', {
  chatId: integer('chat_id').primaryKey(),
  seen:   integer('seen').notNull().default(0),
});

import { api, db } from 'sdk';
import { counters } from 'schema';
import { sql } from 'sdk/db';

export default async function (message) {
  const chatId = message.chat.id;

  const [row] = await db.insert(counters)
    .values({ chatId, seen: 1 })
    .onConflictDoUpdate({
      target: counters.chatId,
      set: { seen: sql`${counters.seen} + 1` },
    })
    .returning()
    .run();

  await api.sendMessage({
    chat_id: chatId,
    text: `Привет! Я уже видел ${row.seen} сообщений от вас.`,
  });
}

npx tgcloud push
npx tgcloud migrate

migrate показывает, что изменится, и спрашивает подтверждение. Безопасные добавления (новая таблица, колонка, индекс) идут пачкой. Удаления и тяжёлые операции подтверждают по одной. Сменить тип колонки автоматически нельзя — это ручной SQL. Удалить таблицу «просто стёрли из schema.js» тоже нельзя: сначала помечают .deprecated('причина'), затем подтверждают drop.

Связи моделируйте обычными колонками вроде userId. Целостность — в коде: сначала родитель, потом дети; при удалении — наоборот.

Справочник команд tgcloud

Команда ищется вверх по дереву до ближайшей .tgcloud/, из подпапки проекта тоже работает.

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

Правки с телефона в BotFather

Тот же облачный проект открывается в @BotFather → бот → Serverless. Можно создать и прогнать обработчик, править lib/, менять схему и применять миграции. Save деплоит. Логи console видны в чате, как у npx tgcloud run.

Начали хендлер в метро — дома npx tgcloud pull заберёт его на ноутбук. Двух разных «источников правды» нет.

Частые ошибки при настройке Telegram Serverless

Telegram Serverless vs Python-хостинг: что выбрать

Serverless закрывает «ответить на апдейт без машины». Хостинг закрывает бота, который живёт сутками: пакеты, файлы, база MySQL, платежи, правки без IDE. Ниже — сравнение по критериям, которые обычно ломают проект через месяц после запуска.

Колонка справа — то, как устроен BotMix: Python-бот в контейнере, каталог готовых решений и ИИ-генератор, который собирает бота из текстового описания. Serverless у Telegram эту связку не повторяет и не обязан: у продуктов разная работа.

Когда хватит Serverless, а когда нужен полноценный бот

Берите Serverless, если вы пишете на JS, бот отвечает на события и состояние умещается в SQLite. Эхо на /start, учёт очков, бэкенд Mini App, тонкая интеграция «пришло сообщение — дернули API».

Переходите на хостинг, когда появляется любая из этих вещей: оплата картами, доступ в канал по подписке, магазин, рассылка базе, разбор фото, видео, свой планировщик, чужие Python-библиотеки, сайт рядом с ботом, правки человеком без Cursor. Такие сценарии разобраны отдельно: магазин в Telegram, бот для рассылок, доступ к каналу за подписку, личный ИИ-ассистент.

Если кода нет и не будет, Serverless всё равно потребует файлы и деплой. В панели BotMix тот же запрос звучит иначе: описали, что бот должен делать, генератор собирает Python, ставит зависимости и запускает контейнер. Каталог закрывает типовые задачи без генерации.

Частые вопросы про Telegram Serverless

Telegram Serverless — это конструктор ботов?

Нет. Нет визуальных блоков и шаблонов «накликал меню». Есть папка с JS, CLI и редактор в BotFather. Сравнение конструкторов и хостинга — в гайде конструктор vs хостинг.

Нужен ли VPS?

Для самого Serverless — нет. Для Python-бота, pip, ffmpeg и круглосуточных рассылок VPS или хостинг для ботов по-прежнему нужен.

Можно ли совместить Mini App и Serverless?

Да: Telegram прямо называет среду бэкендом для ботов и Mini Apps. Саму веб-страницу приложения всё равно где-то хостить. Serverless хранит данные и отвечает Bot API.

Сколько это стоит?

На странице core.telegram.org/bots/serverless нет прайса, бесплатного пакета и лимитов CPU. Перед боевой нагрузкой смотрите BotFather и свежую справку Telegram: условия могут появиться позже запуска.

Безопасны ли токены?

CLI-токен не должен попадать в git и в чаты. API-токен бота в Serverless-проект не кладут: вызовы api.* идут с платформенными правами. Для CI — переменная окружения TGCLOUD_TOKEN.

Что делать дальше

Если цель — понять фичу Telegram и поднять эхо-бота, этого мануала достаточно: включили Serverless, создали проект, залогинились, написали handlers/message.js, сделали push.

Если нужен бот, который продаёт, принимает оплату, ходит в ИИ-модели, работает с фото и живёт месяцами без вашего ноутбука — соберите его на Python-хостинге. В BotMix это либо готовый бот из каталога, либо описание своими словами в ИИ-генераторе.