Telegram Bot API

Як розгорнути Telegram-бота: VPS, Docker і serverless-хостинг

· 9 хв читання

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

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

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

Long polling (getUpdates)Вебхук (setWebhook)
МережаЛише вихідний HTTPS; працює за NATПублічна HTTPS-адреса, порти 443, 80, 88 або 8443, IPv4
ПроцесЦикл, що працює постійноHTTP-обробник; може бути serverless
ЕкземпляриРівно один на токенМожна кілька за однією адресою
Де запускати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, задеплойте та зареєструйте адресу воркера з тим самим секретом:

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 показує правильну адресу й жодних свіжих помилок.
  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-адреса на порту 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, розмітка й кнопки

Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.

Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати

Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.

Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення

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

Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму

Як дізнатися chat id у Телеграм через 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.