Bot di Telegram: webhook o polling lungo, secret_token e distribuzione su serverless
Два способа получать обновления
Bot API отдаёт входящие сообщения двумя взаимоисключающими способами:
- Long polling — бот сам вызывает
getUpdatesс параметромtimeout, Telegram держит запрос открытым, пока не появятся обновления. Нужен постоянно работающий процесс, входящие порты не нужны. - Webhook — Telegram отправляет каждое обновление POST-запросом на ваш HTTPS-адрес. Процесс может не работать постоянно, поэтому вариант подходит для serverless.
Одновременно они не работают: пока установлен webhook, getUpdates возвращает ошибку 409 Conflict. Это частая причина «бот перестал отвечать», когда на сервере запустили локальную копию в режиме polling.
| | Long polling | Webhook | |---|---|---| | Где запускать | VPS, контейнер, локально | serverless, любой HTTPS-сервер | | Публичный адрес | не нужен | HTTPS на порту 443, 80, 88 или 8443 | | Разработка | просто, работает из-за NAT | нужен туннель для локальной отладки | | Простой процесса | обновления ждут в очереди | Telegram повторяет доставку |
Для разработки и бота на одном VPS long polling проще. Для деплоя на Vercel, Cloudflare Workers или в функции — только webhook.
Webhook с secret_token
URL вебхука нельзя считать секретом. Без проверки любой, кто его узнал, отправит поддельное обновление от имени любого пользователя. Параметр secret_token при установке вебхука решает это: Telegram будет передавать его в заголовке X-Telegram-Bot-Api-Secret-Token каждого запроса.
SECRET=$(openssl rand -hex 32) # допустимы A-Z, a-z, 0-9, _ и -, до 256 символов
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
-d "url=https://example.com/api/telegram" \
-d "secret_token=${SECRET}" \
-d 'allowed_updates=["message","callback_query"]' \
-d "drop_pending_updates=true"allowed_updates ограничивает типы событий, которые приходят на вебхук, — меньше лишних вызовов функции. drop_pending_updates выбрасывает накопившуюся очередь, чтобы бот после деплоя не ответил на сотню старых сообщений.
Обработчик на Next.js
// app/api/telegram/route.ts
import { timingSafeEqual } from "node:crypto";
import { db } from "@/lib/db";
const TOKEN = process.env.TELEGRAM_BOT_TOKEN!;
const SECRET = process.env.TELEGRAM_WEBHOOK_SECRET!;
function validSecret(header: string | null) {
if (!header) return false;
const a = Buffer.from(header), b = Buffer.from(SECRET);
return a.length === b.length && timingSafeEqual(a, b);
}
async function tg(method: string, body: unknown) {
const res = await fetch(`https://api.telegram.org/bot${TOKEN}/${method}`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(body),
});
if (!res.ok) console.error("telegram", method, res.status, await res.text());
}
export async function POST(req: Request) {
if (!validSecret(req.headers.get("x-telegram-bot-api-secret-token"))) {
return new Response("forbidden", { status: 403 });
}
const update = await req.json();
const first = await db.query(
"INSERT INTO tg_updates (update_id) VALUES ($1) ON CONFLICT DO NOTHING",
[update.update_id]
);
if (first.rowCount === 0) return new Response("ok");
const msg = update.message;
if (msg?.text === "/start") {
await tg("sendMessage", { chat_id: msg.chat.id, text: "Привет! Пришлите номер заказа." });
} else if (msg?.text) {
await tg("sendMessage", { chat_id: msg.chat.id, text: await lookupOrder(msg.text) });
}
return new Response("ok");
}Почему так:
- Секрет проверяется первым и через
timingSafeEqual. - Дедупликация по `update_id`. Если ответ не пришёл вовремя или вернулся не 2xx, Telegram повторит доставку. Без дедупликации пользователь получит два ответа или два созданных заказа.
- Всегда 200 после обработки, даже если сообщение не распознано. Ошибочный статус вызовет повторы, и очередь обновлений встанет.
- Токен бота в URL. Не логируйте полные URL запросов к Bot API: токен окажется в логах. В примере логируется только метод и статус.
Ответить можно и прямо в теле ответа на вебхук, вернув JSON с полем method (например, {"method":"sendMessage","chat_id":...,"text":"..."}). Это экономит один исходящий запрос, но вы не узнаете, доставлено ли сообщение.
Особенности serverless
- Время выполнения. Если обработка долгая (вызов LLM, генерация файла), функция может не уложиться в лимит платформы, а Telegram сочтёт доставку неуспешной. Быстро ответьте 200 и перенесите работу в очередь или фоновую задачу, а результат отправьте через
sendMessage. - Параллельность. Параметр
max_connectionsвsetWebhook(от 1 до 100, по умолчанию 40) задаёт, сколько одновременных запросов шлёт Telegram. Порядок сообщений одного пользователя при параллельной обработке не гарантирован. Если бот ведёт пошаговый диалог, храните состояние в базе и учитывайте гонки. - Холодный старт. Первое сообщение после простоя обрабатывается медленнее. Для ботов это обычно приемлемо.
Диагностика
curl -s "https://api.telegram.org/bot${BOT_TOKEN}/getWebhookInfo"Ответ содержит pending_update_count (сколько обновлений ждут доставки), last_error_date и last_error_message. Типичные ошибки:
Wrong response from the webhook: 403 Forbidden— секрет в переменных окружения не совпадает с тем, что передан вsetWebhook.SSL errorилиConnection refused— недоступный адрес или сертификат, которому Telegram не доверяет.- Растущий
pending_update_count— обработчик отвечает ошибкой или не укладывается во время.
Когда остаться на long polling
Если бот живёт на собственном сервере, нагрузка небольшая и не хочется публиковать HTTPS-эндпоинт, long polling надёжен и прост. Библиотеки вроде grammY и Telegraf поддерживают оба режима, и переход потом занимает несколько строк.