Telegram Bot API

Как задеплоить Telegram-бота: VPS, Docker и serverless-хостинг

· 9 мин чтения

Чтобы задеплоить Telegram-бота, запустите его код на машине, которая работает круглосуточно и видит api.telegram.org, и выберите способ получения апдейтов: long polling через getUpdates — работает на любом сервере без домена — или вебхук, которому нужен публичный HTTPS-URL. Для бота на polling обычно берут небольшой VPS с systemd или Docker-контейнер; для бота на вебхуке подходят serverless-платформы вроде Cloudflare Workers. В этом гайде — каждый вариант с готовыми конфигами, а также логи, перезапуски и чек-лист перед запуском.

Polling или вебхук на сервере

У Telegram два взаимоисключающих способа получать апдейты, и в обоих случаях недоставленные апдейты хранятся не дольше 24 часов. От выбора зависит, какой хостинг нужен телеграм-боту:

Long polling (getUpdates)Вебхук (setWebhook)
СетьТолько исходящий HTTPS; работает за NATПубличный HTTPS-URL, порты 443, 80, 88 или 8443, IPv4
ПроцессПостоянно работающий циклHTTP-обработчик; может быть serverless
ЭкземплярыРовно один на токенМожно несколько за одним URL
Где запускатьVPS, Docker, домашний серверVPS с reverse proxy, Cloudflare Workers, AWS Lambda, Vercel

Если polling у вас уже работает, оставьте его: в официальном гайде по вебхукам Telegram прямо пишет, что в getUpdates нет ничего плохого. Переходите на вебхук, когда этого требует платформа или нужно распределить нагрузку между несколькими экземплярами.

Бот на polling, готовый к деплою

Код для продакшена должен делать три вещи: читать токен из переменной окружения, писать логи в stdout и переживать сетевые ошибки, а не падать. Этот эхо-бот делает всё это и при старте вызывает deleteWebhook, потому что getUpdates не работает, пока установлен вебхук:

import logging
import os
import time

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("bot")

TOKEN = os.environ["BOT_TOKEN"]  # никогда не пишите токен в коде
API = f"https://api.telegram.org/bot{TOKEN}"


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def main():
    call("deleteWebhook")  # polling и вебхук взаимоисключающие
    log.info("started as @%s", call("getMe")["username"])
    offset = 0
    while True:
        try:
            updates = call("getUpdates", offset=offset, timeout=30)
        except Exception:
            log.exception("getUpdates failed, retrying in 5 s")
            time.sleep(5)
            continue
        for update in updates:
            offset = update["update_id"] + 1
            msg = update.get("message")
            if msg and "text" in msg:
                try:
                    call("sendMessage", chat_id=msg["chat"]["id"], text="Echo: " + msg["text"])
                except Exception:
                    log.exception("update %s failed", update["update_id"])


if __name__ == "__main__":
    main()
const TOKEN = process.env.BOT_TOKEN; // никогда не пишите токен в коде
if (!TOKEN) throw new Error("BOT_TOKEN is not set");
const API = `https://api.telegram.org/bot${TOKEN}`;
const log = (...args) => console.log(new Date().toISOString(), ...args);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

await call("deleteWebhook"); // polling и вебхук взаимоисключающие
log("started as @" + (await call("getMe")).username);

let offset = 0;
while (true) {
  let updates;
  try {
    updates = await call("getUpdates", { offset, timeout: 30 });
  } catch (err) {
    log("getUpdates failed, retrying in 5 s:", err.message);
    await sleep(5000);
    continue;
  }
  for (const update of updates) {
    offset = update.update_id + 1;
    const msg = update.message;
    if (!msg?.text) continue;
    try {
      await call("sendMessage", { chat_id: msg.chat.id, text: "Echo: " + msg.text });
    } catch (err) {
      log(`update ${update.update_id} failed:`, err.message);
    }
  }
}

Сохраните код как bot.py (с requests в requirements.txt) или bot.mjs (Node.js 18+, без зависимостей). Фреймворки из списка библиотек берут цикл на себя, но шаги деплоя ниже остаются теми же.

Телеграм-бот на VPS с systemd

VPS — это обычная Linux-машина. Пусть systemd запускает бота при загрузке и перезапускает после падения:

  1. Создайте пользователя без права входа и скопируйте код в /opt/mybot; для Python создайте там виртуальное окружение и установите зависимости.
  2. Запишите токен в /etc/mybot.env строкой BOT_TOKEN=123456789:AAEexampleTokenReplaceWithYours и ограничьте доступ: chmod 600.
  3. Создайте unit-файл /etc/systemd/system/mybot.service:
[Unit]
Description=Telegram bot
After=network-online.target
Wants=network-online.target

[Service]
User=mybot
WorkingDirectory=/opt/mybot
EnvironmentFile=/etc/mybot.env
ExecStart=/opt/mybot/.venv/bin/python -u bot.py
# Node.js: ExecStart=/usr/bin/node bot.mjs
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Включите сервис и следите за логами:

sudo systemctl daemon-reload
sudo systemctl enable --now mybot
journalctl -u mybot -f        # логи в реальном времени
sudo systemctl restart mybot  # после обновления кода

Для вебхука на том же VPS запустите бота как HTTP-сервер на локальном порту и поставьте перед ним nginx или Caddy, который терминирует TLS на порту 443; обработчик с проверкой секретного токена есть в гайде по вебхукам.

Деплой Telegram-бота в Docker

Контейнер упаковывает рантайм и зависимости, поэтому бот одинаково работает на ноутбуке и на любом Docker-хосте. Dockerfile для бота на Python:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY bot.py .
CMD ["python", "-u", "bot.py"]
# Node.js: FROM node:22-slim, COPY bot.mjs ., CMD ["node", "bot.mjs"]

Соберите и запустите образ, передав токен при запуске, а не зашив его в образ:

docker build -t mybot .
docker run -d --name mybot --restart unless-stopped --env-file .env mybot
docker logs -f mybot

--restart unless-stopped поднимает бота после падений и перезагрузки хоста. Держите .env вне Git и вне образа (добавьте его в .dockerignore). При передеплое бота на polling сначала остановите старый контейнер и только потом запускайте новый: два контейнера с одним токеном приводят к ошибке 409 Conflict в getUpdates.

Serverless: телеграм-бот на Cloudflare Workers

Serverless-платформы запускают код только при входящем запросе, поэтому им нужен вебхук. На Cloudflare Workers стандартный адрес workers.dev уже отдаёт HTTPS на порту 443. Этот Worker проверяет заголовок с секретным токеном, сразу отвечает и доделывает работу в фоне через ctx.waitUntil:

// worker.js: деплой командой "npx wrangler deploy"
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    if (request.method !== "POST" || url.pathname !== "/telegram/webhook") {
      return new Response("Not found", { status: 404 });
    }
    const enc = new TextEncoder();
    const received = enc.encode(request.headers.get("X-Telegram-Bot-Api-Secret-Token") ?? "");
    const expected = enc.encode(env.WEBHOOK_SECRET);
    if (received.byteLength !== expected.byteLength ||
        !crypto.subtle.timingSafeEqual(received, expected)) {
      return new Response("Forbidden", { status: 403 });
    }
    const update = await request.json();
    ctx.waitUntil(handleUpdate(update, env)); // сразу отвечаем 200, работа продолжается
    return new Response("OK");
  },
};

async function handleUpdate(update, env) {
  const msg = update.message;
  if (!msg?.text) return;
  const res = await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/sendMessage`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ chat_id: msg.chat.id, text: "Echo: " + msg.text }),
  });
  if (!res.ok) console.error("sendMessage failed", res.status, await res.text());
}

Сохраните оба значения как секреты Worker, задеплойте и зарегистрируйте URL воркера с тем же секретом:

npx wrangler secret put BOT_TOKEN
npx wrangler secret put WEBHOOK_SECRET
npx wrangler deploy

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mybot.example.workers.dev/telegram/webhook", "secret_token": "replace-with-your-random-secret"}'

Или заполните форму setWebhook в Bot API Tester. Та же схема работает на AWS Lambda (за HTTPS function URL или API Gateway) и в функциях Vercel: разобрать JSON-тело, проверить заголовок, быстро вернуть 2XX. Платформы ограничивают время работы функции и фоновых задач, поэтому долгую работу выносите в очередь. Telegram повторяет запрос при любом ответе, отличном от 2XX, так что функция, которая упала или не уложилась во время, получит тот же апдейт ещё раз.

Бесплатный и недорогой хостинг для телеграм-бота

Требования к вебхуку на любом хостинге

После каждого деплоя открывайте getWebhookInfo в Bot API Tester: растущий pending_update_count или свежий last_error_message означают, что Telegram не может доставить апдейты.

Переменные окружения, логи и перезапуски

Чек-лист деплоя

  1. Токен берётся из переменной окружения или секрета; getMe на сервере проходит успешно.
  2. На один токен — ровно один экземпляр с polling или вебхук с secret_token, но не то и другое сразу.
  3. Процесс автоматически перезапускается после падений и перезагрузок.
  4. Логи собираются и не содержат токенов.
  5. Ошибка в одном апдейте логируется, а не роняет бота; обработчики вебхука быстро возвращают 2XX.
  6. Для вебхука getWebhookInfo показывает правильный URL и нет свежих ошибок.
  7. Для экспериментов используется отдельный тестовый бот или тестовый сервер Telegram, а не боевой токен.

Проблемы после деплоя

СимптомПричина и решение
409 Conflict: terminated by other getUpdates requestС одним токеном опрашивают два экземпляра (старый контейнер, ваш ноутбук). Оставьте один.
409 Conflict с упоминанием активного вебхукаВебхук всё ещё установлен. Вызовите deleteWebhook перед polling.
401 UnauthorizedПеременная с токеном пустая, с опечаткой или токен отозван. Проверьте его через getMe.
Локально работает, на сервере молчитИсходящий HTTPS к api.telegram.org заблокирован или файл окружения не подгружается. Смотрите логи.
Бот на вебхуке ничего не получаетСмотрите last_error_message в getWebhookInfo: TLS, неверный порт, 403 из-за несовпадения секрета или падающий обработчик.

Только начинаете? Сначала прочитайте, как создать бота в Telegram, а потом возвращайтесь к деплою.

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

Где разместить Telegram-бота?

На любой машине, которая может делать исходящие HTTPS-запросы: VPS, Docker-хост, домашний сервер или serverless-платформа. Боту на getUpdates публичный адрес не нужен; боту на вебхуке нужен публичный HTTPS-URL на порту 443, 80, 88 или 8443.

Что выбрать для бота на сервере: polling или вебхук?

В продакшене работают оба варианта. Long polling через getUpdates проще всего на VPS или в Docker: не нужны ни домен, ни сертификат. На serverless-платформах нужен вебхук, потому что код там запускается только при входящем запросе.

Почему после деплоя бот получает 409 Conflict?

Либо всё ещё установлен вебхук, а бот опрашивает getUpdates (вызовите deleteWebhook), либо одновременно работают две копии бота: например, старый и новый контейнер во время деплоя или ваш ноутбук и сервер. На один токен — ровно один экземпляр с polling.

Как сделать, чтобы бот работал 24/7?

Запускайте его под супервизором, который перезапустит процесс после падения и перезагрузки: сервис systemd с Restart=always на VPS или Docker-контейнер с --restart unless-stopped. Пишите логи в stdout и смотрите их через journalctl или docker logs.

Можно ли запустить Telegram-бота на Cloudflare Workers?

Да, в режиме вебхука. Worker получает каждый апдейт POST-запросом, проверяет заголовок X-Telegram-Bot-Api-Secret-Token и вызывает Bot API через fetch. Его HTTPS-адрес на workers.dev регистрируется через setWebhook. Цикл long polling в эту модель не вписывается.

Где хранить токен бота на сервере?

В переменной окружения, которая загружается из файла с доступом только для пользователя бота, или в хранилище секретов платформы (например, секрет Worker). Никогда не коммитьте токен в Git и не зашивайте в Docker-образ. Если токен утёк, отзовите его в @BotFather.

Как создать бота в Телеграм: от @BotFather до первого сообщения

Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.

Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим

Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.

Ошибки Telegram Bot API: что означает каждая ошибка и как её исправить

Ошибки Telegram Bot API с решениями: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 и retry_after. Таблица причин и код обработки.

Лимиты Telegram Bot API: сообщения в секунду, ошибка 429 и размеры файлов

Все лимиты Telegram Bot API в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.

Команды Telegram-бота: setMyCommands, области видимости и deep link для /start

Настройка команд Telegram-бота: /setcommands в @BotFather, setMyCommands с областями и языками, параметр /start в deep link и команды /cmd@bot в группах.

Клавиатуры Telegram-бота: инлайн-кнопки, callback_data и reply-клавиатура

Кнопки Telegram-бота: инлайн-клавиатура с callback_data, answerCallbackQuery, редактирование сообщения после нажатия, reply-клавиатура и ForceReply.

Интеграция n8n и Telegram: подключение бота, Telegram Trigger и отправка сообщений

Как подключить Telegram к n8n: токен бота в Access Token, вебхук Telegram Trigger по публичному HTTPS, отправка сообщений по chat id и разбор ошибок.

Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки

Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.

Токен бота Telegram: как получить, где найти, как проверить и отозвать

Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.

Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление

Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.

Как узнать chat id в Telegram: пользователь, группа, канал и тема форума

Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.

Инлайн-бот Telegram: как включить inline mode и отвечать на инлайн-запросы

Как сделать инлайн-бота Telegram: включить inline mode через @BotFather или setMySettings, обработать inline_query и ответить через answerInlineQuery.

Оплата Telegram Stars в боте: счета, pre-checkout, возвраты и подписки

Приём оплаты в Telegram Stars в боте: sendInvoice с XTR, pre_checkout_query, successful_payment, возвраты, подписки и пример на Python и JS.

Тестовый сервер Telegram: как тестировать бота в тестовом окружении

Тестовый сервер Telegram для ботов: вход в тестовое окружение, создание тестового бота, запросы к Bot API через /test/ и переключатель TEST в тестере.

Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»

Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».

TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты

Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.

Примеры виджетов Telegram: готовый HTML и код бота на Python

Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.

Виджеты Telegram: интерактивный HTML прямо в сообщениях бота

Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.

Тестирование Telegram Mini App: от браузера до отладки на телефоне

Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.