Telegram Bot API

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

· 9 хв читання

Вебхук телеграм-бота — це HTTPS-адреса вашого сервера, на яку Telegram сам надсилає POST-запит із кожним новим апдейтом. Вмикається він одним викликом setWebhook, перевіряється через getWebhookInfo, а видаляється методом deleteWebhook. Нижче — вимоги до сервера, готові команди curl, обробники з перевіркою secret_token на Python і Node.js та розбір типових помилок, зокрема з n8n на localhost.

Вебхук чи getUpdates: що обрати

ПараметрgetUpdates (long polling)Вебхук
Хто ініціюєБот сам опитує TelegramTelegram надсилає апдейти на ваш сервер
Що потрібноБудь-яка машина з інтернетом, навіть за NATПублічна HTTPS-адреса й сертифікат
Коли зручноРозробка, невеликі боти, немає доменуПродакшн, serverless, навантаження з піками

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

Вимоги до сервера для вебхука

Як встановити вебхук через setWebhook

ПараметрНавіщо потрібен
urlHTTPS-адреса обробника. Порожній рядок видаляє вебхук
secret_token1–256 символів A-Z, a-z, 0-9, _, -; приходить у заголовку X-Telegram-Bot-Api-Secret-Token
allowed_updatesЯкі типи апдейтів надсилати, наприклад ["message", "callback_query"]
drop_pending_updatestrue — відкинути апдейти, що накопичилися
max_connectionsОдночасних з'єднань із сервером: 1–100, за замовчуванням 40
certificateПублічний ключ самопідписаного сертифіката (лише файлом, multipart)
ip_addressФіксована IP-адреса замість отриманої з DNS
export BOT_TOKEN="123456789:AAEexampleTokenReplaceWithYours"
export WEBHOOK_SECRET="$(openssl rand -hex 32)"   # збережіть — він потрібен обробнику

curl -s "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  --data-urlencode "url=https://bot.example.com/telegram/webhook" \
  -d "secret_token=$WEBHOOK_SECRET" \
  --data-urlencode 'allowed_updates=["message","callback_query"]' \
  -d drop_pending_updates=true \
  -d max_connections=40
{"ok": true, "result": true, "description": "Webhook was set"}

Зверніть увагу: якщо не передати allowed_updates, збережеться попередній список. Порожній список означає всі типи, крім chat_member, message_reaction і message_reaction_count. Спробувати без термінала можна в Bot API Tester на методі setWebhook.

Із самопідписаним сертифікатом у CN можна вказати IP-адресу сервера, а публічний ключ передати файлом:

openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.key -x509 -days 365 \
  -out public.pem -subj "/CN=203.0.113.10"

curl -s "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  -F "url=https://203.0.113.10:8443/telegram/webhook" \
  -F "certificate=@public.pem" \
  -F "secret_token=$WEBHOOK_SECRET"

Перевірка вебхука: getWebhookInfo

curl -s "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"
{
  "ok": true,
  "result": {
    "url": "https://bot.example.com/telegram/webhook",
    "has_custom_certificate": false,
    "pending_update_count": 12,
    "last_error_date": 1793275800,
    "last_error_message": "Wrong response from the webhook: 502 Bad Gateway",
    "max_connections": 40,
    "allowed_updates": ["message", "callback_query"]
  }
}

Ту саму перевірку зручно запускати в getWebhookInfo у Bot API Tester, щойно апдейти перестають приходити.

Обробник вебхука з перевіркою secret_token

Адреса вебхука публічна, тож будь-хто може надіслати на неї підроблений апдейт. Заголовок X-Telegram-Bot-Api-Secret-Token відсікає такі запити: порівнюйте його із секретом за сталий час і відповідайте 403 на чужі запити.

Python, FastAPI (pip install fastapi uvicorn) або Node.js, Express (npm i express):

import hmac
import os

from fastapi import FastAPI, Header, HTTPException, Request

WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]
app = FastAPI()


@app.post("/telegram/webhook")
async def telegram_webhook(
    request: Request,
    x_telegram_bot_api_secret_token: str | None = Header(default=None),
):
    received = (x_telegram_bot_api_secret_token or "").encode()
    if not hmac.compare_digest(received, WEBHOOK_SECRET.encode()):
        raise HTTPException(status_code=403)
    update = await request.json()
    # покладіть апдейт у чергу й одразу поверніть 200
    print("update", update["update_id"])
    return {"ok": True}
import crypto from 'node:crypto';
import express from 'express';

const expected = Buffer.from(process.env.WEBHOOK_SECRET);
const app = express();
app.use(express.json());

app.post('/telegram/webhook', (req, res) => {
  const received = Buffer.from(req.get('X-Telegram-Bot-Api-Secret-Token') ?? '');
  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) {
    return res.sendStatus(403);
  }
  res.sendStatus(200); // спершу відповідь Telegram
  handleUpdate(req.body).catch(console.error); // потім обробка
});

async function handleUpdate(update) {
  console.log('update', update.update_id);
}

app.listen(8000); // TLS термінує nginx або Caddy перед застосунком

Порт 8000 не входить до чотирьох дозволених, тому застосунок має стояти за nginx чи Caddy, які приймають HTTPS на 443 і проксіюють запити далі. Стежте, щоб секрет на сервері й у setWebhook збігався: інакше ваш же обробник відповідатиме 403, а Telegram повторюватиме доставку.

Відповідайте 2xx швидко

Бонус: у відповіді на вебхук можна одразу викликати метод Bot API. Поверніть JSON із полем method і параметрами — Telegram виконає запит, але дізнатися його результат ви не зможете:

{"method": "sendMessage", "chat_id": 123456789, "text": "Прийнято!"}

Як видалити вебхук телеграм-бота

Щоб повернутися до getUpdates, викличте deleteWebhook. Параметр drop_pending_updates=true заразом відкине накопичені апдейти — це зручно, якщо бот довго не працював і не повинен відповідати на старі повідомлення:

curl -s "https://api.telegram.org/bot$BOT_TOKEN/deleteWebhook?drop_pending_updates=true"

Без цього параметра черга збережеться, і getUpdates віддасть її повністю. Той самий ефект, що й deleteWebhook, дає setWebhook із порожнім url.

Типові помилки вебхука

Bad Request: bad webhook: An HTTPS URL must be provided for webhook — у url передано адресу з http:// або без схеми. Потрібен саме https:// і публічний домен чи IP.

409 Conflict під час виклику getUpdates — вебхук встановлено, і long polling заблоковано. Якщо вебхук поставив інший сервіс (наприклад, n8n), а вам потрібен polling, викличте deleteWebhook. Якщо ж потрібен вебхук, зупиніть скрипт, який викликає getUpdates.

n8n на localhost. Telegram-тригер у n8n реєструє вебхук через setWebhook, а адреса на кшталт http://localhost:5678 не підходить двічі: це не HTTPS, і Telegram не може достукатися до вашого комп'ютера. Потрібна публічна HTTPS-адреса: n8n на сервері з доменом за nginx чи Caddy із сертифікатом або тунель на зразок cloudflared чи ngrok. Публічну адресу треба передати самій n8n (зазвичай через змінну оточення WEBHOOK_URL), щоб вона реєструвала в Telegram саме її.

Один бот — один вебхук. Якщо два сервіси чи два воркфлоу використовують той самий токен, вони перезаписують вебхук один одному. Дайте кожному сервісу окремого бота.

Вебхук встановлено, але апдейти не приходять. Дивіться last_error_message у getWebhookInfo. Типові причини: непідтримуваний порт, неповний ланцюжок сертифікатів, редирект, обробник падає з 5xx або файрвол не пропускає підмережі Telegram. Перевірити TLS із зовнішньої машини допоможе curl -v https://bot.example.com/telegram/webhook.

Вебхук приймає апдейти, а відповіді надсилаються як завжди — через sendMessage, докладніше в гайді як надіслати повідомлення через бота. Якщо бот лише створюється, почніть з інструкції зі створення бота, а з проблемами токена зазирніть у гайд токен бота Telegram. Про обмеження на кількість з'єднань і зберігання апдейтів — в огляді ліміти Telegram Bot API.

Поширені запитання

Як видалити вебхук телеграм-бота?

Викличте https://api.telegram.org/bot<token>/deleteWebhook. З параметром drop_pending_updates=true заразом видаляться апдейти, що накопичилися. Після цього знову працює getUpdates.

Чи можна використовувати вебхук і getUpdates одночасно?

Ні, ці способи взаємовиключні. Поки вебхук встановлено, getUpdates повертає 409 Conflict.

Які порти підтримує вебхук Telegram?

Лише 443, 80, 88 і 8443, причому HTTPS обов'язковий на будь-якому з них. Порт, відмінний від 443, вказують просто в URL: https://example.com:8443/webhook.

Чи потрібен платний SSL-сертифікат для вебхука?

Ні. Підійде безкоштовний сертифікат, наприклад Let's Encrypt, або самопідписаний — його треба завантажити в параметрі certificate під час виклику setWebhook.

Як перевірити, що запит на вебхук надіслав саме Telegram?

Передайте secret_token у setWebhook: Telegram додаватиме його в заголовок X-Telegram-Bot-Api-Secret-Token кожного запиту. Порівнюйте заголовок з очікуваним значенням і відхиляйте запити без нього.

Чому Telegram надсилає той самий апдейт повторно?

Ваш сервер відповів не 2xx або не відповів вчасно, і Telegram повторив доставку. Відповідайте 200 одразу, важку обробку виносьте у фон, а дублікати відсікайте за update_id.

Як створити бота в Телеграм: від @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: повідомлення на секунду, помилка 429 і розміри файлів

Ліміти Telegram Bot API в одному місці: повідомлення на секунду, помилка 429 і retry_after, платні розсилки, розміри файлів, довжина тексту й підпису.

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

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

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

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

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

Як дізнатися chat id у Телеграм через getUpdates: особистий чат, група, супергрупа, канал і тема форуму. Формати id з -100 і що робити з порожнім result.

Тестовий сервер 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.