Telegram боты: webhook немесе ұзақ сауалнама, secret_token және серверсіз орналастыру
Жаңартуларды алудың екі жолы
Bot API кіріс хабарларды бір-бірін жоққа шығаратын екі жолмен жеткізеді:
- Ұзақ сауалнама - боттың өзі
getUpdatesпараметріменtimeoutшақырады, Telegram жаңартулар пайда болғанша сұрауды ашық сақтайды. Тұрақты жұмыс істейтін процесс қажет, кіріс порттары қажет емес. - Webhook - Telegram әрбір жаңартуды POST сұрауымен HTTPS мекенжайыңызға жібереді. Процесс үнемі жұмыс істемеуі мүмкін, сондықтан опция серверсіз.
Олар бір уақытта жұмыс істемейді: веб-хук орнатылған кезде getUpdates 409 Conflict қатесін қайтарады. Бұл серверде сұрау режимінде жергілікті көшірме іске қосылған кезде «бот жауап беруді тоқтатты» деген жалпы себеп.
| | Ұзақ дауыс беру | Webhook | |---|---|---| | Қайда жүгіру керек | VPS, контейнер, жергілікті | серверсіз, кез келген HTTPS сервері | | Қоғамдық мекенжай | қажет емес | 443, 80, 88 немесе 8443 портындағы HTTPS | | дамыту | қарапайым, NAT | арқасында жұмыс істейді жергілікті отладка үшін туннель қажет | | Қарапайым процесс | жаңартулар кезек күтуде | Telegram жеткізуді қайталайды |
Әзірлеу және бір VPS-тегі бот үшін ұзақ сауалнама оңайырақ. Vercel, Cloudflare Workers немесе функцияда орналастыру үшін - тек веб-хук.
Құпия_белгісі бар вебхук
Webhook 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 жүйесіне енгізбеңіз: таңбалауыш журналдарда аяқталады. Мысалда тек әдіс пен күй ғана журналға жазылады.
Сондай-ақ, method өрісімен JSON қайтара отырып (мысалы, {"method":"sendMessage","chat_id":...,"text":"..."}) веб-хук жауабының негізгі бөлігінде тікелей жауап беруге болады. Бұл бір шығыс сұрауды сақтайды, бірақ хабардың жеткізілгенін білмейсіз.
Серверсіз мүмкіндіктер
- Орындау уақыты. Өңдеу ұзақ болса (LLM қоңырауы, файлды генерациялау), функция платформа шегіне сәйкес келмеуі мүмкін және Telegram жеткізуді сәтсіз деп санайды. 200 арқылы жылдам жауап беріңіз және жұмысты кезекке немесе фондық тапсырмаға жылжытыңыз және нәтижені
sendMessageарқылы жіберіңіз. - Параллельдік.
setWebhookішіндегіmax_connectionsпараметрі (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ұлғаюы - өңдеуші қатемен жауап береді немесе уақыт бітті.
Ұзақ дауыс беруде қашан қалу керек
Егер бот өз серверінде тұрса, жүктеме жеңіл және HTTPS соңғы нүктесін жариялағыңыз келмесе, ұзақ сауалнама сенімді және қарапайым. GramY және Telegraf сияқты кітапханалар екі режимді де қолдайды, содан кейін көшу бірнеше жолды алады.