Guruhlar va kanallardagi botlar

Botni guruhga yoki kanalga qo'shish mumkin: u buyruqlarga javob beradi, yangi a'zolarni kutib oladi, spamni o'chiradi, kanalga post joylaydi. Bot API o'sha-o'sha — faqat chat_id manfiy bo'ladi va bir nechta yangi metod hamda yangilanish qo'shiladi.

Botni guruhga qo'shish

1. Bot egasi (siz) hech narsa qilmasa ham bo'ladi: botlarni guruhga qo'shish standart holatda yoqilgan. O'chirish uchun — @ZaminBot'da /setjoingroups (u kanallarga ham taalluqli). Holatni getMe'dagi can_join_groups ko'rsatadi.
2. Guruh egasi yoki "A'zo qo'shish" huquqli admin guruh ma'lumotlaridagi Botlar bo'limida botni username bo'yicha qo'shadi.
3. Bot my_chat_member (left → member) va o'zi ham ichida bo'lgan new_chat_members xizmat xabarini oladi. Shu paytdan boshlab chat.id ma'lum — bot guruhga yoza oladi.
4. Moderatsiya kerak bo'lsa, guruh egasi (yoki "Admin tayinlash" huquqli admin) botni admin qiladi va kerakli huquqlarni beradi (jadval). Bot my_chat_member (member → administrator, huquqlar bilan) oladi.

• Tarix yo'q. Bot qo'shilishidan oldingi xabarlarni hech qachon ko'rmaydi: ular botga shifrlanmagan va endi shifrlab bo'lmaydi. Bot chiqarilib, qayta qo'shilsa ham, oraliqdagi xabarlar unga ko'rinmaydi.
• Kimlar qo'shilmaydi: @ZaminBot, bloklangan (suspended) botlar, /setjoingroups o'chirilgan botlar. Davra chatlariga bot qo'shib bo'lmaydi.
• Chiqarish: guruh egasi yoki "Foydalanuvchilarni cheklash" huquqli admin (bot admin bo'lsa — faqat ega yoki uni admin qilgan odam). Bot my_chat_member (→ kicked) oladi. Bot o'zi ham chiqishi mumkin: leaveChat (→ left).
• Limitlar: bitta guruhda ko'pi bilan 20 ta bot; bitta bot ko'pi bilan 200 ta guruh va kanalda (birgalikda).

Privacy mode: bot nimani ko'radi

Oddiy qilib aytganda: bot guruhda faqat o'ziga qaratilgan xabarlarni oladi. Aniqrog'i, privacy mode yoqilgan bo'lsa (standart holat), bot faqat quyidagilarni oladi:

1. Buyruqlar — / bilan boshlanadigan xabar (yoki fayl izohi): /start, /help, shuningdek /help@SizningBot. /help@BoshqaBot sizga kelmaydi; oddiy /help esa guruhdagi har bir botga boradi.
2. @eslatishlar — matnda @SizningBot alohida so'z sifatida bor (katta-kichik harf farqsiz).
3. Botning o'z xabariga javoblar (reply).
4. Hamma xabarlar — lekin faqat guruh egasi botni admin qilib, unga "Barcha xabarlarni o'qish" huquqini bergan bo'lsa (pastda).

Bundan tashqari bot doim oladi: server baribir biladigan xizmat voqealari (kim qo'shildi, chiqdi yoki chiqarildi, guruh nomi o'zgardi, botning o'zi qo'shildi, admin qilindi yoki chiqarildi) va o'z xabarlaridagi tugma bosilishlari.

Bot hech qachon ko'rmaydi: boshqa xabarlarni, iqtibos qilingan matnni, havola ko'rinishlarini (link preview), "kimdan forward qilingan"ni, boshqa botlarning xabarlarini, reaksiyalarni, qadashlarni, "o'qildi" belgilarini, telefon raqamlar, profil rasmlari, kontaktlar, onlayn holat va bot qo'shilishidan oldingi tarixni. Odamlar shaxsiy chatdagidek psevdonim id bilan ko'rinadi.

"Barcha xabarlarni o'qish"

Bot guruhdagi barcha xabarlarni faqat ikki shart birga bajarilganda oladi:

• bot o'sha guruhning admini, va
• guruh egasi unga "Barcha xabarlarni o'qish" huquqini o'zi, aniq bergan.

Boshqa yo'l yo'q: bot egasining @ZaminBot'dagi /setprivacy sozlamasi o'zi hech qachon "barcha xabarlar"ni yoqmaydi. Uning ta'siri:

• Privacy holati bot guruhga qo'shilgan paytda shu guruh uchun "suratga olinadi" va keyin hech qachon o'zgarmaydi (admin qilish yoki huquqlarni o'zgartirish ham uni yangilamaydi). /setprivacy'ni keyin o'zgartirsangiz, faqat bot qayta qo'shilganda hisobga olinadi.
• Privacy mode'i o'chiq holda qo'shilgan botni faqat guruh egasi admin qila oladi va faqat "Barcha xabarlarni o'qish" huquqini shu so'rovning o'zida yoqib: ilova ikkinchi marta tasdiq so'raydi, busiz server 409 BOT_PRIVACY_OFF qaytaradi.
• Ilova guruhdagi har bir bot uchun suratga olingan holatni (GroupBot.privacyMode) va haqiqiy holatni (readsAllMessages) ko'rsatadi.

Boshqa adminlar bu huquqni bera olmaydi va privacy mode'i o'chiq botni admin qila olmaydi. Bot egasi guruh rozi bo'lmagan holda botni jimgina "hamma narsani o'quvchi"ga aylantira olmaydi.

Bunday guruhda har bir a'zoning ilovasi doimiy ogohlantirish ko'rsatadi: "🤖 @Bot bu guruhdagi barcha xabarlarni o'qiy oladi (ular Zamin serveridan uchidan-uchiga shifrlanmagan)". can_read_all_group_messages (my_chat_member, getChatMember, getChatAdministrators) va ilovadagi readsAllMessages haqiqiy holatni bildiradi: true — bot hozir barcha xabarlarni oladi.

Bu uchidan-uchiga shifrlash uchun nimani anglatadi

Ochiq aytamiz, chunki foydalanuvchilar sizning botingizga ishonadi:

• Bot telefon emas — u sizning serveringizda ishlaydigan dastur va xabarlarni Bot API orqali oddiy JSON ko'rinishida oladi. Shuning uchun guruhdagi har bir bot shu guruh uchun o'z shifrlash kalitiga ega ("bot qurilmasi"), uning maxfiy qismi esa Zamin serverida saqlanadi (serverda shifrlangan holda).
• A'zoning telefoni xabarni botga ham shifrlasa (buyruq, @eslatish, javob yoki "barcha xabarlar"), o'sha xabarni Zamin serveri ham, bot egasi ham o'qiy oladi. Bunday xabar uchidan-uchiga shifrlangan emas deb hisoblang.
• Botga shifrlanmagan xabarlar a'zolarning telefonlari orasida uchidan-uchiga shifrlangan bo'lib qoladi — ularni na server, na bot o'qiy oladi.
• Qaysi xabar botga borishini yuboruvchining telefoni hal qiladi. Server ham tekshiradi: botning nusxasini ochib, u haqiqatan buyruq / @eslatish / botga javob ekanini tekshiradi va mos kelmaganini botga bermaydi.
• Fayl izohida buyruq bo'lsa, bot o'sha faylni ham oladi (fayl kaliti xabar ichida keladi).
• Botning guruhdagi xabarlari ham a'zolar telefonlari uchun shifrlanadi, lekin ularni server yozgan — demak bot yuborgan matnni server biladi.
• Kanallar uchidan-uchiga shifrlanmagan (postlar serverda, hozirgidek).

Bot nusxasida nima bor

A'zoning telefoni botga xabarning qisqartirilgan nusxasini shifrlaydi; server ham nusxani o'qishdan oldin xuddi shu maydonlarni olib tashlaydi:

• Iqtibos yo'q. Javob qilingan xabarning matni va muallifi nusxada yo'q — faqat uning id'si. Shu sababli reply_to_message boshqa odamning xabari uchun mazmunsiz keladi (message_id, chat, date va server biladigan from); to'liq faqat botning o'z xabari.
• Havola ko'rinishi (link preview) yo'q — faqat matnning o'zi.
• "Kimdan forward qilingan" yo'q.
• Kontaktlar hech qachon botga shifrlanmaydi (guruhda contact kelmaydi).

Siz — bot egasi — uchun xulosa: botga kelgan guruh xabarlarini kerakli ish tugagach saqlamang, log'larga to'liq yozmang, va "barcha xabarlarni o'qish"ni faqat haqiqatan kerak bo'lsa so'rang (masalan, flood'ga qarshi moderator). Kam ma'lumot saqlang.

Chat id'lari

• Guruh va kanal id'lari tasodifiy, lekin doimiy — ularni bazangizda saqlang. Ichki hisob id'lari botga hech qachon berilmaydi.
• Ochiq guruh yoki kanal uchun chat_id sifatida "@username" ham ishlaydi (bot unda a'zo bo'lsa).
• Noma'lum id, bot a'zo bo'lmagan chat yoki botni boshlamagan odamning shaxsiy chati — hammasi uchun bir xil javob: 400 Bad Request: chat not found.
• message_id: guruhda — guruhning umumiy xabar raqami (hamma a'zolar va botlar uchun bir xil, o'sib boradi, bot ko'rmagan xabarlar sabab oraliqlar bo'ladi). Kanal va izohlarda — bot birinchi marta ko'rganda beriladigan raqam.
• Odamlarning from.id'si shaxsiy chatdagi bilan bir xil psevdonim raqam: bitta odam sizning botingizga guruhda ham, shaxsiy chatda ham bir xil id bilan ko'rinadi, boshqa botga esa boshqa id bilan.

Yangilanishlar

O'chirishlar, reaksiyalar va qadashlar haqida yangilanish kelmaydi. Webhook yoki getUpdates'da allowed_updates ishlatsangiz, yangi turlarni ro'yxatga qo'shishni unutmang — ro'yxat bot uchun saqlanadi.

Guruhdagi buyruq

Admin /warn buyrug'ini Vali'ning xabariga javob qilib yozdi. reply_to_message — boshqa odamning xabari, shuning uchun unda mazmun yo'q, faqat raqami va muallifi (botning nusxasida iqtibos yo'q, server esa odamlar xabarlarining matnini saqlamaydi — bot nusxasi):

{
  "update_id": 501,
  "message": {
    "message_id": 815,
    "from": {
      "id": 4810235517,
      "is_bot": false,
      "first_name": "Ali",
      "last_name": "Valiyev",
      "username": "ali",
      "language_code": "uz"
    },
    "chat": {
      "id": -4012345678,
      "type": "group",
      "title": "Dasturchilar"
    },
    "date": 1791106200,
    "text": "/warn@ObHavoBot",
    "reply_to_message": {
      "message_id": 812,
      "chat": {
        "id": -4012345678,
        "type": "group",
        "title": "Dasturchilar"
      },
      "date": 1791106160,
      "from": {
        "id": 5203318874,
        "is_bot": false,
        "first_name": "Vali",
        "username": "vali",
        "language_code": "uz"
      }
    }
  }
}

Yangi a'zo

{
  "update_id": 502,
  "message": {
    "message_id": 816,
    "chat": {
      "id": -4012345678,
      "type": "group",
      "title": "Dasturchilar"
    },
    "date": 1791106200,
    "from": {
      "id": 4810235517,
      "is_bot": false,
      "first_name": "Ali",
      "last_name": "Valiyev",
      "username": "ali",
      "language_code": "uz"
    },
    "new_chat_members": [
      {
        "id": 5203318874,
        "is_bot": false,
        "first_name": "Vali",
        "username": "vali",
        "language_code": "uz"
      }
    ]
  }
}

from — amalni bajargan odam. Bu xizmat xabarini deleteMessage bilan o'chirish mumkin (can_delete_messages kerak).

Bot admin qilindi

{
  "update_id": 503,
  "my_chat_member": {
    "chat": {
      "id": -4012345678,
      "type": "group",
      "title": "Dasturchilar"
    },
    "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": "administrator",
      "can_change_info": false,
      "can_delete_messages": true,
      "can_restrict_members": true,
      "can_invite_users": false,
      "can_pin_messages": true,
      "can_post_messages": false,
      "can_edit_messages": false,
      "can_promote_members": false,
      "can_manage_video_chats": false,
      "can_read_all_group_messages": false
    }
  }
}

chat_member

{
  "update_id": 504,
  "chat_member": {
    "chat": {
      "id": -4012345678,
      "type": "group",
      "title": "Dasturchilar"
    },
    "from": {
      "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
    },
    "date": 1791106200,
    "old_chat_member": {
      "user": {
        "id": 5203318874,
        "is_bot": false,
        "first_name": "Vali",
        "username": "vali",
        "language_code": "uz"
      },
      "status": "member"
    },
    "new_chat_member": {
      "user": {
        "id": 5203318874,
        "is_bot": false,
        "first_name": "Vali",
        "username": "vali",
        "language_code": "uz"
      },
      "status": "kicked"
    }
  }
}

chat_member faqat qo'shilish (left → member), chiqish va chiqarish (member → left) hamda ban'da (member → kicked) keladi. Admin tayinlash, huquq o'zgarishi yoki jim qilishda kelmaydi.

Kanal posti va izoh

{
  "update_id": 505,
  "channel_post": {
    "message_id": 37,
    "sender_chat": {
      "id": -1004012345678,
      "type": "channel",
      "title": "Ob-havo yangiliklari",
      "username": "obhavo_news"
    },
    "chat": {
      "id": -1004012345678,
      "type": "channel",
      "title": "Ob-havo yangiliklari",
      "username": "obhavo_news"
    },
    "date": 1791106200,
    "text": "Ertaga Toshkentda +18°C, yomg'ir 🌧"
  }
}

{
  "update_id": 506,
  "message": {
    "message_id": 3,
    "from": {
      "id": 5203318874,
      "is_bot": false,
      "first_name": "Vali",
      "username": "vali",
      "language_code": "uz"
    },
    "chat": {
      "id": -1007012345678,
      "type": "supergroup",
      "title": "Ob-havo yangiliklari — comments"
    },
    "date": 1791106200,
    "text": "Rahmat!",
    "message_thread_id": 37,
    "reply_to_message": {
      "message_id": 37,
      "chat": {
        "id": -1004012345678,
        "type": "channel",
        "title": "Ob-havo yangiliklari",
        "username": "obhavo_news"
      },
      "date": 1791106200
    }
  }
}

Guruhda xabar yuborish

• sendMessage, sendPhoto, sendDocument, sendVideo, sendAudio — chat_id manfiy. Javobdagi message.chat — guruh.
• Faqat inline klaviatura (reply klaviatura → 400 only inline keyboards are supported in groups). Tugmani istalgan a'zo bosishi mumkin; answerCallbackQuery javobi faqat bosgan odamga ko'rinadi.
• Bot admin bo'lmasa, guruhning a'zolar uchun ruxsatlari unga ham amal qiladi ("faqat adminlar yozadi" guruhida bot yoza olmaydi).
• editMessageText, editMessageReplyMarkup — faqat botning o'z xabarlari, 48 soat ichida. Guruhda editMessageText fayl xabarining izohini ham almashtiradi.
• Bot xabari guruhning har bir a'zosining eng so'nggi faol 10 ta qurilmasi uchun shifrlanadi; boshqa botlar uni ko'rmaydi (botlar bir-birini ko'rmaydi). Kimdadir 10 tadan ko'p qurilma bo'lsa, eskiroq telefonlarida bot xabari qulflangan ko'rinadi (o'sha telefonda qayta kirish yoki eski qurilmadan chiqish kerak).

Admin amallari va huquqlar

Har bir amal bajarilganda botning huquqi qayta tekshiriladi. Guruh egasi va adminlariga admin amallari hech qachon qo'llanmaydi. user_id — bot ko'rgan psevdonim id.

"A'zo qo'shish" huquqi botga berilishi mumkin, lekin unga mos metod yo'q. "Admin tayinlash" va "Qo'ng'iroqlarni boshqarish" botlarga berilmaydi (botlarda can_promote_members va can_manage_video_chats doim false; odam-adminlarda — haqiqiy qiymati). Huquq yetmasa: 400 Bad Request: not enough rights to …; egasi yoki adminga qo'llansa: can't remove chat owner / user is an administrator of the chat.

Limitlar

Har bir limit bir xil javob beradi: 429 Too Many Requests: retry after N va parameters.retry_after. Rad etilgan so'rov hech narsa qilmagan (xabar yuborilmagan, olgan tokenlari qaytarilgan) — retry_after soniyadan keyin uni qayta yuboring.

Ko'p a'zo birdan qo'shilsa, har biriga alohida salom yozmang: bir nechta ismni bitta xabarga birlashtiring yoki salomni o'tkazib yuboring.

Guruhdagi fayllar

• Qabul qilish. Bot faylni faqat xabar unga shifrlangan bo'lsa oladi (masalan, izohida buyruq bor rasm yoki "barcha xabarlar" rejimi): xabarda photo, document, video, audio, voice yoki video_note bo'ladi. Fayl kaliti faqat shu bot uchun saqlanadi va faqat faylni yuklagan a'zoning xabaridan olinadi (bot birinchi olgan kalitini saqlab qoladi: keyin boshqa birov uni almashtira olmaydi).
• Yuklab olish. getFile va /file/bot<TOKEN>/… — shaxsiy chatdagidek. Server faylni bo'lakma-bo'lak ochib, oqim (stream) bilan beradi: chegara 50 MB, Content-Type doim application/octet-stream (turini mime_type yoki fayl nomidan aniqlang).
• Yuborish. Multipart yoki file_id — shaxsiy chatdagi cheklovlar bilan (rasm ≤20 MB, boshqalar ≤50 MB, rasm qayta kodlanadi va EXIF olib tashlanadi). Server faylni tekshiradi, so'ng uchidan-uchiga shifrlab saqlaydi.
• Guruhda olingan file_id'ni boshqa guruh yoki kanalga qayta yuborish mumkin, lekin shaxsiy chatga — yo'q (wrong file identifier). Guruh yoki kanalga file_id bilan qayta yuborishda server faylni qayta kodlaydi, shuning uchun u fayl uzatish limitiga yuklash sifatida kiradi.
• Chiqarilgan bot o'sha guruh fayllariga kirishni yo'qotadi: kalitlari o'chiriladi, yuklab olishda a'zolik tekshiriladi: getFile — invalid file_id, yuklab olish — 404 file not found, qayta yuborish — wrong file identifier.
• Bir vaqtda bot bo'yicha 3 ta yuklab olish va 3 ta yuklash (umumiy 16 tadan); oshsa — 429, retry_after: 1.

Kanallar

Kanalga botni egasi yoki "Admin tayinlash" huquqli admin qo'shadi. Kanalda bot doim admin; huquqlari: post joylash, boshqalarning postlarini tahrirlash, o'chirish, qadash, ma'lumotni o'zgartirish. Rasmiy kanallarga bot qo'shib bo'lmaydi. Kanallar uchidan-uchiga shifrlanmagan.

• Kontent filtri va shartlar. Bot postlari va tahrirlari odamlarning postlari kabi kontent filtridan o'tadi: rad etilsa — 400 Bad Request: <sabab>. Yangi post uchun bot egasi Zamin foydalanish shartlarini qabul qilgan bo'lishi kerak, aks holda 403 Forbidden: the bot's owner must accept Zamin's terms of use first.
• Postlarda tugma yo'q. reply_markup bilan yuborish yoki editMessageReplyMarkup → 400 Bad Request: channel posts can't have buttons.
• Bot izoh yoza olmaydi. Izohlar chatiga yuborish → 400 Bad Request: method is not available for this chat. Izohlarni o'qiy oladi va (huquq bilan) o'chira oladi.
• Post oddiy kanal posti bo'lib chiqadi: obunachilar bildirishnoma oladi, javobda from yo'q, sender_chat — kanal.
• Bot faqat admin bo'lib turgan vaqtda yangi postlar va izohlarni ko'radi.
• getChatMember kanalda (va izohlar chatida) faqat botning o'zi, kanal egasi va adminlar uchun ishlaydi; boshqa har kim uchun — 400 Bad Request: user not found (Zamin botga kanal obunachilarini oshkor qilmaydi).
• leaveChat izohlar chati id'si bilan — 400; kanaldan chiqish uchun kanal id'sini bering.

import os
import requests

TOKEN = os.environ["ZAMIN_BOT_TOKEN"]
API = f"https://api.zamin.app/bot{TOKEN}"
CHANNEL = "@obhavo_news"  # ochiq kanal username'i yoki manfiy id (-100...)

post = requests.post(
    f"{API}/sendMessage",
    json={"chat_id": CHANNEL, "text": "Ertaga Toshkentda +18°C, yomg'ir 🌧"},
    timeout=15,
).json()
if not post["ok"]:
    raise SystemExit(post["description"])  # masalan: not enough rights to send messages to the chat
message_id = post["result"]["message_id"]

# Tahrirlash va qadash
requests.post(f"{API}/editMessageText", json={"chat_id": CHANNEL, "message_id": message_id, "text": "Ertaga Toshkentda +17°C, yomg'ir 🌧"}, timeout=15)
requests.post(f"{API}/pinChatMessage", json={"chat_id": CHANNEL, "message_id": message_id}, timeout=15)

Darslik: moderator bot

Rose uslubidagi to'liq moderator bot — yangi a'zolarni kutib olish, xizmat xabarlarini o'chirish, /warn (3 ta — ban), /mute 10m, /ban, /unban, flood'ga qarshi himoya va /rules: Moderator bot darsligi.

Telegram'dan farqlar

• Guruhlar uchidan-uchiga shifrlangan; botga kelgan xabarlarni server va bot egasi o'qiy oladi (yuqorida).
• "Barcha xabarlarni o'qish" uchun bot admin bo'lishi va guruh egasi bu huquqni aniq berishi kerak; /setprivacy o'zi buni yoqmaydi va faqat bot qo'shilgan paytda "suratga olinadi".
• Boshqa odamlar xabariga reply_to_message mazmunsiz keladi; to'liq faqat botning o'z xabari. Havola ko'rinishi, forward manbasi va kontaktlar botga bormaydi.
• Qadash uchun bot doim admin can_pin_messages huquqiga muhtoj.
• Bot izoh yoza olmaydi, kanal postlarida tugma yo'q.
• banChatMember doim muddatsiz; restrictChatMember'da faqat can_send_messages; unpinChatMessage doim joriy qadalgan xabarni oladi; getChatMember kanalda faqat bot, ega va adminlar uchun.
• chat_member faqat qo'shilish, chiqish, chiqarish va ban'da.
• /setjoingroups kanallarga ham taalluqli.
• Guruhda reply klaviatura yo'q; inline rejim, forum mavzulari, ovozli chatlar va taklif havolasi metodlari yo'q.