Telegram Bot API asoslari: token, Update, polling va webhook

Qisqacha: Telegram bot — Telegram serveri bilan oddiy HTTPS orqali gaplashadigan backend dastur: https://api.telegram.org/bot<token>/<metod>. Foydalanuvchi yozgan har narsa Update obyekti bo'lib keladi. Uni ikki yo'l bilan olasiz: long polling (getUpdates ni timeout bilan qayta-qayta so'rash, offset bilan tasdiqlash) yoki webhook (Telegram o'zi sizning HTTPS manzilingizga POST qiladi, secret_token sarlavhasi bilan). Ikkalasi bir vaqtda ishlamaydi. Token — botning to'liq kaliti, uni parol kabi saqlang.

Bu darsda

• Bot qanday ishlashini va token nima ekanini tushuntirasiz.
• Update obyektini o'qiysiz va turini aniqlaysiz.
• getUpdates va offset qanday tasdiqlashini kanon tajribasida ko'rasiz.
• Short va long polling'ni o'lchov bilan solishtirasiz.
• Webhook'ni secret_token bilan himoyalaysiz va 409 xatosini tanib olasiz.

Oldin bilishingiz kerak: Built-in fetch va undici, http.createServer: req va res, Server timeout'lari va keep-alive, Bildirishnoma tizimi arxitekturasi.

Oldingi darsda bildirishnoma markazi to'rtta kanalni kutdi: email, SMS va push tayyor. To'rtinchisi — Telegram. O'zbekistonda u ko'pchilik uchun asosiy messenjer: eslatma Telegram'da kelsa, darhol o'qiladi. Bu darsdan yangi blok boshlanadi — Telegram botlari (sakkiz dars).

Diqqat: Bu darslarda haqiqiy bot, haqiqiy token va Telegram serveri ishlatilmaydi. Kanon Bot API shaklini takrorlaydigan lokal soxta server (simulyator) yozdi: so'rovlar POST /bot<token>/<metod>, xato javoblari, limitlar. Hujjatdagi cheklovlar (matn 4096 belgi, webhook bor paytda getUpdates → 409) unda bor; 429 chegaralari va xato matnlarining aniq so'zlari esa taxminiy. Haqiqiy bot yaratish — o'quvchining o'z qadami.

1. Nega bu kerak?

vazifalar foydalanuvchisi Malika email'ni kamdan-kam ochadi, push'ni esa telefon tejamkor rejimda bostiradi. Telegram'ni esa kuniga 50 marta ochadi. Bot orqali:

• muddat eslatmasi Telegram'ga keladi;
• "Bajarildi" tugmasi bilan vazifani shu yerning o'zida yopadi (keyingi darslarda);
• /vazifalar — bugungi ro'yxat.

Bot — "sun'iy foydalanuvchi" emas. U sizning serveringizdagi dastur, Telegram esa uning uchun pochtachi: foydalanuvchi xabarlarini sizga yetkazadi va sizning javoblaringizni foydalanuvchiga olib boradi.

O'xshatish: bot — mehmonxona qabulxonasi, Telegram — telefon stansiyasi. Mehmon qo'ng'iroq qiladi, stansiya uni qabulxonaga ulaydi. Qabulxona stansiyaga ikki xil yo'l bilan ishlay oladi: o'zi har daqiqa "menga qo'ng'iroq bormi?" deb so'raydi (polling) yoki stansiyaga raqamini beradi va u o'zi qo'ng'iroq qiladi (webhook).

2. Bot, token va birinchi so'rov

2.1 BotFather va token

Bot @BotFather — Telegram'ning rasmiy boti — orqali yaratiladi: /newbot, nom va …bot bilan tugaydigan username. Javobda token keladi: 123456789:AA… shaklidagi satr — oldin botning raqamli ID'si, keyin maxfiy qism. Bu hujjat bo'yicha; kanon BotFather'dan foydalanmadi.

Token — login ham, parol ham. Kimda token bo'lsa, u bot nomidan yozadi, foydalanuvchilar xabarlarini o'qiydi va webhook'ni o'z serveriga buradi. Shuning uchun:

• token faqat .env da (Sirlarni boshqarish): TELEGRAM_BOT_TOKEN=…;
• git'ga, skrinshotga, chatga — hech qachon;
• sizib chiqsa — BotFather'da /revoke va yangi token.

Token so'rov URL'ining ichida turadi. Demak URL'ni loglaydigan har qatlam (proksi, xato kuzatuvchi, console.log(url)) tokenni ham yozib qo'yadi. Loglarda tokenni yashiring.

2.2 Bot API — oddiy HTTP

Har metod — POST https://api.telegram.org/bot<token>/<metod>, parametrlar — JSON (fayllar uchun multipart). Javob doim bir xil shaklda:

{ "ok": true, "result": { } }

yoki xato:

{ "ok": false, "error_code": 401, "description": "Unauthorized" }

Kanon lokal soxta serverga xom fetch bilan so'rov yubordi (grammy 1.46.0 paketi keyingi darsda; bu bo'limda kutubxonasiz):

const TOKEN = process.env.TELEGRAM_BOT_TOKEN;
const API = process.env.TELEGRAM_API ?? "https://api.telegram.org";

const api = (metod, parametr = {}) =>
  fetch(`${API}/bot${TOKEN}/${metod}`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(parametr),
  }).then((r) => r.json());

console.log((await api("getMe")).result);

Kanon natijasi (soxta server, token 123456:SOXTA…):

getMe: {"id":123456,"is_bot":true,"first_name":"Vazifalar","username":"vazifalar_soxta_bot","can_join_groups":true,"can_read_all_group_messages":false,"supports_inline_queries":true}
noto'g'ri token: {"ok":false,"error_code":401,"description":"Unauthorized"}

getMe — "men kimman?": tokenni tekshirishning eng arzon yo'li. Ilova ishga tushganda uni bir marta chaqiring — oldingi darslardagi verify() ning Telegram varianti. can_read_all_group_messages: false — privacy mode: guruhda bot faqat o'ziga qaratilgan xabarlarni ko'radi (guruh botlari darsida).

API o'zgaruvchisi — sinov uchun: kanon testlarida u lokal soxta serverga qaraydi, prodda esa sukutdagi api.telegram.org.

3. Update obyekti

3.1 Tuzilishi

Foydalanuvchi botga "salom" yozdi. Bot buni Update sifatida oladi. Kanon soxta serverdan olgan xom Update (bitta uzun JSON qator — from, chat va text ga qarang):

{"update_id":1001,"message":{"message_id":1,"from":{"id":42,"is_bot":false,"first_name":"Aziz","language_code":"uz"},"chat":{"id":42,"type":"private"},"date":1793111807,"text":"salom"}}

Shaxsiy suhbatda chat.id va from.id bir xil (42). Guruhda — farqli: chat.id guruhniki (manfiy son), from.id — yozgan odamniki. Javob chat.id ga yuboriladi.

3.2 Update turlari

Bitta Update'da faqat bitta "yuk" maydoni bo'ladi: message, edited_message, channel_post, callback_query (tugma bosildi), inline_query, my_chat_member (botni guruhga qo'shishdi yoki bloklashdi) va boshqalar. Turini aniqlash:

const TURLAR = [
  "message", "edited_message", "channel_post", "callback_query",
  "inline_query", "my_chat_member", "pre_checkout_query",
];

function updateTuri(u) {
  return TURLAR.find((t) => t in u) ?? "boshqa";
}

const updatelar = [
  { update_id: 1001, message: { chat: { id: 42 }, text: "salom" } },
  { update_id: 1002, callback_query: { data: "bajarildi:7" } },
  { update_id: 1003, my_chat_member: { chat: { id: -100123 } } },
  { update_id: 1004, poll: { id: "5" } },
];
for (const u of updatelar) console.log(u.update_id, updateTuri(u));

Konsolda:

1001 message
1002 callback_query
1003 my_chat_member
1004 boshqa

Kutubxonalar (grammY) aynan shu ishni qiladi va sizga bot.on("message:text", …) beradi. Kutmagan turingiz kelsa, bot uni e'tiborsiz qoldirishi kerak — yiqilmasligi. my_chat_member alohida e'tiborga loyiq: foydalanuvchi botni bloklaganda shu keladi. Bildirishnoma markazidagi telegram_ulanishlar.faol = false ni darhol shu yerda qo'yish mumkin.

4. getUpdates va offset

4.1 Tasdiqlash qanday ishlaydi

Telegram Update'larni o'zida navbatda saqlaydi (hujjatga ko'ra 24 soatgacha). getUpdates navbatni beradi, lekin o'chirmaydi. Kanon tajribasi:

getUpdates (offset'siz): 2 ta; birinchisi: {"update_id":1001,…}
yana offset'siz: 2 ta — o'sha update'lar QAYTA keldi (tasdiqlanmagan)
offset = 1003: 0 ta — tasdiqlandi, navbatda 0

(Birinchi qatordagi Update yuqorida to'liq berilgan — bu yerda qisqartirdik.)

Qoida: offset = oxirgi update_id + 1 yuborilsa, Telegram undan kichik hammasini tasdiqlangan deb o'chiradi. Mantiqni kichik modelda ko'ramiz:

const server = { navbat: [], keyingi: 1001 };
function yozadi(matn) {
  server.navbat.push({ update_id: server.keyingi++, text: matn });
}
function getUpdates(offset = 0) {
  server.navbat = server.navbat.filter((u) => u.update_id >= offset);
  return server.navbat.map((u) => u.update_id);
}

yozadi("salom");
yozadi("/start");
console.log(getUpdates());
console.log(getUpdates());
console.log(getUpdates(1003));
yozadi("yana");
console.log(getUpdates(1003));

Konsolda:

[ 1001, 1002 ]
[ 1001, 1002 ]
[]
[ 1003 ]

Bu — "kamida bir marta" (at-least-once) yetkazish: Update'ni ishlab, keyin offset ni oshirsangiz va o'rtada jarayon o'lsa, Update qayta keladi. Teskarisi — avval offset, keyin ishlash — Update'ni yo'qotishi mumkin. Birinchisi xavfsizroq, lekin ishlov idempotent bo'lishi kerak: bir Update ikki marta kelsa, ikki marta vazifa yaratilmasin (3-mashq).

4.2 Short polling va long polling

Short polling — getUpdates ni timeout: 0 bilan har N millisekundda so'rash. Bo'sh javoblar ko'p, xabar esa keyingi so'rovgacha kutadi. Long polling — timeout: 30 (soniya): Telegram javobni ushlab turadi va Update kelishi bilan darhol qaytaradi (WebSocket va Server-Sent Events darsidagi polling g'oyasining server varianti). Kanon soxta serverda 5 ta xabar bilan o'lchadi:

short (0 s, har 500 ms)  kechikish mediana 214 ms, so'rovlar 10 (5 xabar uchun)
long (timeout 10 s)      kechikish mediana 14 ms, so'rovlar 5 (5 xabar uchun)

Long polling 15 marta tez va so'rovlar ikki barobar kam. Haqiqiy Telegram bilan tarmoq kechikishi qo'shiladi — bu raqamlar faqat usulning o'zi farqini ko'rsatadi. Amalda short polling ishlatilmaydi: kutubxonalar sukutda long polling qiladi.

sequenceDiagram
  participant B as Bot (server)
  participant T as Telegram
  participant U as Foydalanuvchi
  B->>T: getUpdates(timeout 30, offset)
  Note over T: javob ushlab turiladi
  U->>T: salom
  T-->>B: [Update 1001]
  B->>T: sendMessage
  B->>T: getUpdates(offset 1002)

Diagrammaga qarang: keyingi getUpdates dagi offset oldingi Update'ni tasdiqlaydi. Bot doim bitta ochiq so'rov ushlab turadi.

5. Webhook

5.1 Qanday ishlaydi

Webhook'da yo'nalish teskari: siz setWebhook({ url, secret_token }) bilan manzil berasiz, Telegram har Update'ni o'sha HTTPS manzilga POST qiladi. Server javob kutmaydi — 200 kelsa, Update tasdiqlangan.

Ishlab chiqishda — polling, prodda — ko'pincha webhook. Batafsil tanlov Bot prodakshnda darsida.

5.2 Ikkalasi bir vaqtda — yo'q

Kanon webhook o'rnatib, keyin getUpdates chaqirdi. Har qatordagi error_code ga qarang:

setWebhook (secret'da bo'shliq): {"ok":false,"error_code":400,"description":"Bad Request: secret token contains unallowed characters"}
setWebhook: {"ok":true,"result":true}
webhook bor paytda getUpdates: {"ok":false,"error_code":409,"description":"Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first"}

409 tarjimasi: "Ziddiyat: webhook faol paytda getUpdates ishlatib bo'lmaydi; avval deleteWebhook bilan o'chiring". Bu xato ko'pincha shunday chiqadi: prodda bot webhook bilan ishlayapti, dasturchi esa lokal kompyuterda xuddi shu token bilan polling'ni yoqdi. Bitta tokenga bitta usul. Ikki polling jarayoni bir vaqtda ham ziddiyatga uchraydi — har bir muhitga (dev, prod) alohida bot.

secret_token — faqat A–Z, a–z, 0–9, _ va -, 256 belgigacha (hujjat bo'yicha; kanon soxta serveri shu qoidani qo'llaydi). Bo'shliq va ! — 400.

5.3 secret_token: Update haqiqatan Telegram'danmi

Webhook manzilingiz — oddiy URL. Uni bilgan har kim soxta Update yuborib, "Aziz /vazifalar_ochir yozdi" deb ko'rsata oladi. Himoya: setWebhook dagi secret_token ni Telegram har so'rovda X-Telegram-Bot-Api-Secret-Token sarlavhasida qaytaradi. Server uni tekshiradi:

import { createServer } from "node:http";
import { timingSafeEqual } from "node:crypto";

const SIR = Buffer.from("maxfiy_Token-123");
const sirTogri = (sarlavha) => {
  const b = Buffer.from(sarlavha ?? "");
  return b.length === SIR.length && timingSafeEqual(b, SIR);
};

const kelgan = [];
const server = createServer(async (req, res) => {
  if (!sirTogri(req.headers["x-telegram-bot-api-secret-token"])) {
    res.writeHead(401).end();
    return;
  }
  let tana = "";
  for await (const b of req) tana += b;
  kelgan.push(JSON.parse(tana).update_id);
  res.writeHead(200).end();
});
await new Promise((r) => server.listen(0, "127.0.0.1", r));
const url = `http://127.0.0.1:${server.address().port}/tg/webhook`;

async function yubor(sir, update) {
  const headers = { "content-type": "application/json" };
  if (sir) headers["x-telegram-bot-api-secret-token"] = sir;
  const r = await fetch(url, {
    method: "POST", headers, body: JSON.stringify(update),
  });
  return r.status;
}

console.log(await yubor("maxfiy_Token-123", { update_id: 1013 }));
console.log(await yubor("notogri", { update_id: 1 }));
console.log(await yubor(undefined, { update_id: 2 }));
console.log("qayta ishlandi:", kelgan);
server.closeAllConnections();
server.close();

Konsolda:

200
401
401
qayta ishlandi: [ 1013 ]

timingSafeEqual — vaqtga chidamli solishtirish (crypto: hash, shifrlash va imzo): oddiy === birinchi farqli belgida to'xtaydi va javob vaqti orqali sirni harfma-harf taxmin qilish nazariy jihatdan mumkin. U bir xil uzunlikdagi buferlarni talab qiladi — shuning uchun avval uzunlik tekshiriladi.

Kanon xuddi shuni grammY'ning tayyor webhookCallback(bot, "express", { secretToken }) bilan sinadi:

bot javobi: "aks: webhook orqali" | webhook yetkazish: [{"status":200,"update_id":1013}]
noto'g'ri secret bilan soxta update: 401 secret token is wrong
secret sarlavhasiz: 401

Natija bir xil. Keyingi darsda grammY bilan aynan shu yo'ldan boramiz.

Tekshirib ko'ring: Webhook ishlovchisi Update'ni olib, bazaga yozdi, keyin xato bilan 500 qaytardi. Nima bo'ladi?

6. Limitlar

Telegram yuborish tezligini cheklaydi. Bot FAQ'ga ko'ra (2026-10-28 da tekshirildi; kanonda haqiqiy server bilan sinalmagan):

FAQ'da yana bir imkoniyat bor: pullik ommaviy yuborish (paid broadcasts). U BotFather'da yoqiladi va chegarani soniyasiga 1 000 gacha ko'taradi. Lekin 30 dan ortiq har xabar Telegram Stars'da (Telegram ichidagi to'lov birligi — Telegram Mini App backendi va Stars darsida) to'lanadi va katta auditoriya talab qilinadi. Kursdagi botlar uchun bu kerak emas.

Oshib ketsa — 429 Too Many Requests va parameters.retry_after (necha soniya kutish). Kanon soxta serveri shunga o'xshash chegaralarni qo'llaydi (aniq qiymatlar taxminiy) — ommaviy yuborish va navbat Bot prodakshnda darsida o'lchanadi. Hozircha qoida: 1 000 foydalanuvchiga eslatmani Promise.all bilan bir zumda emas, navbat va tezlik chegarasi bilan yuboriladi.

7. Hujumchi nigohi

Oxirgi qator nozik: Update ichidagi from.id ni Telegram qo'yadi, unga ishonsa bo'ladi — faqat Update haqiqatan Telegram'dan kelgan bo'lsa. secret_token siz webhook'da hujumchi istalgan from.id ni yozadi.

8. Ko'p uchraydigan xatolar

9. Mashqlar

Mashqlar kurs/mashqlar/29/19-bot-api/ da.

1-mashq (oson): bo'shliqlarni to'ldiring

• Botni yaratadigan rasmiy bot —
• Tokenni tekshiradigan eng arzon metod —
• Update'larni tasdiqlash uchun getUpdates parametri —
• Webhook faol paytda getUpdates xato kodi —
• Webhook so'rovidagi sir sarlavhasi — X-Telegram-Bot-Api-

2-mashq (o'rta): javob qaysi chatga

chatId(update) yozing: message, edited_message, channel_post, callback_query.message yoki my_chat_member ichidagi chat.id ni qaytarsin, topilmasa null (masalan, inline_query — chatsiz). Guruh ID'si (-1001234567890) JavaScript'da xavfsiz butun sonmi — tekshiring. Ishora: ?? zanjiri va ?. (??, ?. va mantiqiy tayinlash).

function chatId(u) {
  const ichki = u.message ?? u.edited_message ?? u.channel_post
    ?? u.callback_query?.message ?? u.my_chat_member;
  return ichki?.chat?.id ?? null;
}

const updatelar = [
  { update_id: 1, message: { chat: { id: 42 }, text: "salom" } },
  { update_id: 2, callback_query: { message: { chat: { id: 42 } } } },
  { update_id: 3, my_chat_member: { chat: { id: -1001234567890 } } },
  { update_id: 4, inline_query: { id: "7", query: "non" } },
];
for (const u of updatelar) console.log(u.update_id, chatId(u));
console.log(Number.isSafeInteger(-1001234567890), 2 ** 31 - 1);

1 42
2 42
3 -1001234567890
4 null
true 2147483647

3-mashq (qiyin): yiqilishda nima yo'qoladi

Navbatda uchta Update bor. sikl(yiqilishOldidan) yozing: getUpdates(offset) dan kelganlarni tartib bilan ishlaydi, har biridan keyin offset = update_id + 1 qiladi. update_id === yiqilishOldidan bo'lsa, ishlamasdan "yiqildi: <id>" qaytaradi (jarayon o'ldi). Uch marta chaqiring: 502 da yiqilish, keyin ikki marta normal. Har safar natija, offset va ishlanganlar ro'yxatini chiqaring. Ishora: getUpdates — filter bilan (filter).

const navbat = [
  { update_id: 501, text: "a" },
  { update_id: 502, text: "b" },
  { update_id: 503, text: "c" },
];
const getUpdates = (offset) =>
  navbat.filter((u) => u.update_id >= offset);

const ishlangan = [];
let offset = 0;
function sikl(yiqilishOldidan) {
  for (const u of getUpdates(offset)) {
    if (u.update_id === yiqilishOldidan) {
      return `yiqildi: ${u.update_id}`;
    }
    ishlangan.push(u.text);
    offset = u.update_id + 1;
  }
  return "tugadi";
}

console.log(sikl(502), offset, ishlangan);
console.log(sikl(null), offset, ishlangan);
console.log(sikl(null), offset, ishlangan);

yiqildi: 502 502 [ 'a' ]
tugadi 504 [ 'a', 'b', 'c' ]
tugadi 504 [ 'a', 'b', 'c' ]

10. Loyiha qadami: kanon tajribasi, modul — keyingi darsda

Bu dars vazifalar-api ga ham, modullarga ham kod qo'shmaydi. Kanon Bot API'ni xom fetch va grammY bilan faqat tajribada sinadi — lokal soxta server bilan. Sabab: xom HTTP bilan bot yozish o'quv uchun foydali, loyihada esa bu ishni kutubxona qiladi. Kanon modul modullar/src/telegram/bot.ts grammY bilan bot yozish darsida boshlanadi: o'sha yerda vazifalar eslatma boti — /start bilan ulanish, /vazifalar, muddat eslatmalari.

Kanon soxta serveri (modullar/test/soxta/telegram.ts) keyingi darslarning hammasida ishlatiladi. U qo'llaydigan hujjat cheklovlari: matn 4096 belgi, caption 1024, callback_data 1–64 bayt, getFile 20 MB, webhook bor paytda getUpdates → 409, secret_token belgilar to'plami. Taxminiy qismlari: 429 chegaralari, xato matnlarining aniq so'zlari, privacy mode.

O'zingiz sinab ko'ring: alohida papkada npm i grammy@1.46.0, BotFather'dan o'zingizning test botingizni oling, tokenni .env ga yozing va «Bot API — oddiy HTTP» bo'limidagi getMe ni haqiqiy api.telegram.org ga yuboring.

11. Real ishda

• O'zbekistonda Telegram botlari — buyurtma, yetkazib berish, xizmat ko'rsatish va ichki jarayonlar uchun keng tarqalgan; ko'p kompaniyada bot — mijoz bilan asosiy kanal.
• Kutubxonalar: grammY (TypeScript, faol rivojlanadi), Telegraf (eski loyihalarda ko'p). Kanon Telegraf'ni o'rnatmadi — taqqoslash hujjat bo'yicha, keyingi darsda.
• Kod review'da — token kodda yoki logda, secret_token yo'qligi, offset xatolari.
• Intervyuda: "Polling va webhook farqi?", "409 Conflict qachon chiqadi?", "Webhook'ni qanday himoyalaysiz?"

Xulosa

• Bot — Telegram bilan HTTPS orqali gaplashadigan server; token — to'liq kalit.
• Update — bitta yuk maydonli obyekt (message, callback_query, my_chat_member …); turini aniqlab, noma'lumini e'tiborsiz qoldiring.
• getUpdates o'chirmaydi; offset = oxirgi + 1 tasdiqlaydi; avval ishlang, keyin tasdiqlang.
• Long polling: kanonda kechikish 14 ms, short polling — 214 ms.
• Webhook va polling birga — 409; webhook — secret_token va tez 200.
• Limitlar (chatga ~1/s, jami ~30/s) — hujjat bo'yicha; 429 da retry_after.

Keyingi dars: grammY bilan bot yozish — kutubxona bilan birinchi bot: middleware tartibi, buyruqlar, filter so'rovlari va kanon bot.ts moduli.

Manbalar

• Telegram Bot API (metodlar, Update, getUpdates, setWebhook, secret_token): https://core.telegram.org/bots/api
• Telegram Bots FAQ (limitlar: 1/s chatga, 20/daqiqa guruhga, ~30/s ommaviy; pullik ommaviy yuborish): https://core.telegram.org/bots/faq — 2026-10-28 da o'qildi, haqiqiy server bilan sinalmagan
• Webhook bo'yicha qo'llanma: https://core.telegram.org/bots/webhooks
• grammY: https://grammy.dev/
• Node.js crypto.timingSafeEqual: https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b
• Kanon tajribasi (IlmHamroh, 2026-10-27): lokal soxta Bot API serveri, grammy 1.46.0, @grammyjs/runner 2.0.3, @grammyjs/auto-retry 2.0.2, Node 24.21.0. Haqiqiy Telegram, BotFather va limitlar — sinalmagan. Webhook tekshiruvi, Update misollari va mashq yechimlari — biz ishga tushirdik (2026-10-28).