Yangilanishlarni olish

Bot uchun har bir voqea — Update. Ularni ikki usuldan biri bilan olasiz: getUpdates (bot o'zi so'raydi) yoki webhook (Zamin sizning serveringizga yuboradi).

Yangilanish turlari

Guruh va kanallardagi yangilanishlar: Guruhlar va kanallar.

Foydalanuvchi o'z xabarini o'chirsa, bot xabardor qilinmaydi.

my_chat_member

Shaxsiy chatda:

Guruh va kanalda: qo'shildi — left → member (kanalda → administrator), admin qilindi — member → administrator (huquqlar bilan), chiqarildi — → kicked, o'zi chiqdi (leaveChat) — → left. Misollar.

{
  "update_id": 18,
  "my_chat_member": {
    "chat": {
      "id": 4810235517,
      "type": "private",
      "first_name": "Ali",
      "last_name": "Valiyev",
      "username": "ali"
    },
    "from": {
      "id": 4810235517,
      "is_bot": false,
      "first_name": "Ali",
      "last_name": "Valiyev",
      "username": "ali",
      "language_code": "uz"
    },
    "date": 1791106200,
    "old_chat_member": {
      "user": {
        "id": 1000001,
        "is_bot": true,
        "first_name": "Ob-havo",
        "username": "ObHavoBot",
        "can_join_groups": true,
        "can_read_all_group_messages": false,
        "supports_inline_queries": false
      },
      "status": "member"
    },
    "new_chat_member": {
      "user": {
        "id": 1000001,
        "is_bot": true,
        "first_name": "Ob-havo",
        "username": "ObHavoBot",
        "can_join_groups": true,
        "can_read_all_group_messages": false,
        "supports_inline_queries": false
      },
      "status": "kicked"
    }
  }
}

getUpdates — long polling

getUpdates navbatdagi yangilanishlarni qaytaradi. Navbat bo'sh va timeout > 0 bo'lsa, server javobni yangilanish kelguncha yoki timeout tugaguncha ushlab turadi. Bu usul eng oddiy: ochiq port, domen yoki sertifikat kerak emas.

To'g'ri tsikl

1. offset'siz (yoki saqlangan qiymat bilan) getUpdates chaqiring.
2. Har bir yangilanishni qayta ishlang va offset = update_id + 1 qiling.
3. Keyingi chaqiruvda shu offset'ni yuboring — oldingilar o'chadi.

Bot qayta ishga tushganda offset yo'qolsa, tasdiqlanmagan yangilanishlar qayta keladi. Muhim botlarda offset'ni faylga yoki bazaga saqlang.

import os
import time
import requests

TOKEN = os.environ["ZAMIN_BOT_TOKEN"]
API = f"https://api.zamin.app/bot{TOKEN}"


def handle(update):
    message = update.get("message")
    if message and "text" in message:
        requests.post(
            f"{API}/sendMessage",
            json={"chat_id": message["chat"]["id"], "text": message["text"]},
            timeout=15,
        )


def main():
    # Webhook o'rnatilgan bo'lsa, getUpdates 409 qaytaradi: avval o'chiramiz
    requests.post(f"{API}/deleteWebhook", timeout=15)
    offset = None
    while True:
        params = {"timeout": 30, "allowed_updates": ["message", "callback_query", "my_chat_member"]}
        if offset is not None:
            params["offset"] = offset
        try:
            r = requests.post(f"{API}/getUpdates", json=params, timeout=40)
            body = r.json()
        except (requests.RequestException, ValueError) as e:
            print("Tarmoq xatosi:", e)
            time.sleep(3)
            continue
        if not body.get("ok"):
            if body.get("error_code") == 401:
                raise SystemExit("Token noto'g'ri yoki bekor qilingan")
            time.sleep((body.get("parameters") or {}).get("retry_after", 3))
            continue
        for update in body["result"]:
            offset = update["update_id"] + 1
            try:
                handle(update)
            except Exception as e:  # bitta yangilanish butun botni to'xtatmasin
                print("Xato:", update["update_id"], e)


if __name__ == "__main__":
    main()

Bir vaqtda faqat bittasi

• Webhook o'rnatilgan bo'lsa, getUpdates 409 Conflict: can't use getUpdates method while webhook is active… qaytaradi. Avval deleteWebhook.
• setWebhook ochiq long poll'ni darhol 409 bilan yopadi.
• Bir vaqtda faqat bitta getUpdates kutishi mumkin: yangi chaqiruv eskisini 409 Conflict: terminated by other getUpdates request… bilan tugatadi. Bu xato ko'rsangiz — botingizning ikkinchi nusxasi ishlayapti.

Navbat: 24 soat / 1000 ta

Olinmagan (yoki webhookka yetkazilmagan) yangilanishlar 24 soat saqlanadi; bitta bot uchun ko'pi bilan 1000 ta — undan oshsa, eng eskilari o'chiriladi. Bot uzoq vaqt o'chiq tursa, eski yangilanishlar yo'qoladi.

Webhooklar

setWebhook bilan HTTPS manzil bersangiz, har bir yangilanish shu manzilga POST qilinadi. Tanasi — bitta Update JSON obyekti.

POST /zamin/webhook HTTP/1.1
Host: bot.example.com
Content-Type: application/json
User-Agent: ZaminBotAPI/1.0
X-Zamin-Bot-Api-Secret-Token: my-long-random-secret

{"update_id":17,"message":{"message_id":13,"from":{…},"chat":{…},"date":1791106200,"text":"/start"}}

Talablar

• Faqat https://. Sertifikat ishonchli markaz tomonidan berilgan bo'lishi kerak (masalan, Let's Encrypt); o'z-o'zidan imzolangan sertifikat ishlamaydi.
• Portlar: 443, 80, 88, 8443 (port ko'rsatilmasa — 443).
• URL'da login/parol bo'lmasin; URL ≤2048 belgi.

Maxfiy sarlavha

setWebhook'da secret_token (1–256 belgi, A-Z a-z 0-9 _ -) bersangiz, har bir so'rov X-Zamin-Bot-Api-Secret-Token sarlavhasi bilan keladi. Sarlavha mos kelmagan so'rovlarni rad eting — webhook manzilingizni topgan har kim soxta yangilanish yubora oladi. Solishtirishni doimiy vaqtli funksiya bilan qiling (Python'da hmac.compare_digest).

Yetkazish va qayta urinish

• Har qanday 2xx status — yetkazildi. Javob tanasi o'qilmaydi (Telegram'dagi kabi javobda metod chaqirish ishlamaydi).
• Kutish vaqti — 10 soniya. Yo'naltirishlarga (3xx) ergashilmaydi: ular xato hisoblanadi.
• Yangilanishlar bot uchun ketma-ket va tartib bilan yetkaziladi: bittasi yetkazilmaguncha keyingisi yuborilmaydi. max_connections saqlanadi, lekin hozircha parallellik yo'q.
• Xato bo'lsa (2xx emas, ulanish xatosi yoki timeout), o'sha yangilanish qayta yuboriladi: kutish 1, 2, 4, 8 … soniyagacha ikki baravar oshadi va ko'pi bilan 10 daqiqa bo'ladi. Urinishlar yangilanish 24 soatdan eskirguncha davom etadi.
• Oxirgi xato getWebhookInfo'da: last_error_message, last_error_date.

SSRF himoyasi: qaysi manzillar rad etiladi

Webhook manzilini istalgan kishi tanlashi mumkin, shuning uchun server ichki tarmoqqa so'rov yubormasligi uchun manzilni o'zi tekshiradi. Host nomi server tomonidan resolve qilinadi va setWebhook paytida ham, har bir yetkazishdan oldin ham tekshiriladi. Tekshirilgan IP manzilga to'g'ridan-to'g'ri ulaniladi (DNS rebinding'dan himoya; SNI va Host sarlavhasi asl nom bilan qoladi). Quyidagilar rad etiladi:

DNS javoblaridan birortasi ham ommaviy bo'lmagan manzil bo'lsa, butun manzil rad etiladi. Host nomida nuqta bo'lishi va faqat a-z 0-9 . - belgilaridan iborat bo'lishi kerak.

Webhook yoki getUpdates?

To'liq misollar: long polling echo bot va Flask webhook.