ZaminDocs

Zamin Bot API v1

Zamin uchun bot yarating

Zamin — uchidan-uchiga shifrlangan messenger, kanallar va Davra. Bot API orqali siz Zamin foydalanuvchilari bilan yozishadigan dasturlar yaratasiz: yordamchilar, do'kon botlari, eslatmalar, bildirishnomalar va boshqalar. Oddiy HTTPS so'rovlar, JSON va istalgan dasturlash tili.

5 daqiqada boshlash Metodlar ro'yxati

Nima qurish mumkin

Suhbat botlariBuyruqlar, savol-javob, yordam xizmati.Menyu va tugmalarInline tugmalar, callback'lar, reply klaviatura.Eslatma va bildirishnomalarVaqti kelganda foydalanuvchiga xabar yuborish.Fayllar bilan ishlashRasm, hujjat, video va audio qabul qilish va yuborish.Deep link'larzamin.app/sizning_bot?start=promo havolalari.Webhook xizmatlariYangilanishlarni o'z serveringizga qabul qilish.Guruh moderatorlariSalom, /warn, /mute, /ban va flood'ga qarshi himoya.Kanal botlariKanalga post joylash, tahrirlash va qadash.

Tez boshlash

Sizga Zamin ilovasi, Python 3 va requests kutubxonasi kerak bo'ladi.

  1. @ZaminBot'ni oching

    Ilovada @ZaminBot'ni toping (yoki havolani oching) va Start'ni bosing. U Zamin botlarini yaratish va boshqarish uchun rasmiy bot.

  2. /newbot yuboring

    Bot nomini yozing (masalan, Ob-havo), so'ng username tanlang: u bot bilan tugashi kerak, masalan obhavo_uz_bot. Username qoidalari.

  3. Tokenni oling

    @ZaminBot tokenni yuboradi. U 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 ko'rinishida bo'ladi. Uni maxfiy saqlang va muhit o'zgaruvchisiga yozing:

    Terminal
    export ZAMIN_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
pip3 install requests

  4. Birinchi skript

    bot.py faylini yarating. U botni tekshiradi va har bir matnli xabarni qaytarib yozadi:

    bot.py
    import os
import requests

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

me = requests.get(f"{API}/getMe", timeout=15).json()["result"]
print(f"@{me['username']} ishga tushdi")

offset = None
while True:
    params = {"timeout": 30}
    if offset is not None:
        params["offset"] = offset
    updates = requests.post(f"{API}/getUpdates", json=params, timeout=40).json()["result"]
    for update in updates:
        offset = update["update_id"] + 1
        message = update.get("message")
        if message and "text" in message:
            requests.post(
                f"{API}/sendMessage",
                json={"chat_id": message["chat"]["id"], "text": f"Siz yozdingiz: {message['text']}"},
                timeout=15,
            )

  5. Ishga tushiring

    Terminal
    python3 bot.py

    Ilovada botingizni oching, Start'ni bosing va biror narsa yozing. Bot javob qaytaradi. Keyingi qadam: darsliklar va Bot API asoslari.

Asosiy tushunchalar

Bot hisobi

Bot — Zamin'dagi maxsus hisob. Uning egasi bor (siz), username'i bot bilan tugaydi va u faqat Bot API orqali boshqariladi. Bot o'zi suhbat boshlay olmaydi: foydalanuvchi avval botni ochib Start'ni bosishi (yoki unga yozishi) kerak. Guruh egasi yoki admini botni guruhga yoki kanalga qo'shishi ham mumkin (Guruhlar va kanallar).

Token

Token — botingizning paroli: <bot_id>:<36 belgi>. U har bir so'rov manzilida bo'ladi: https://api.zamin.app/bot<TOKEN>/getMe. Server tokenning faqat xeshini saqlaydi, shuning uchun uni qayta ko'rsatib bo'lmaydi: @ZaminBot'dagi /token ham yangi token beradi. Tokenni himoyalash.

Yangilanishlar (updates)

Bot uchun sodir bo'lgan voqealar: yangi xabar, tahrirlangan xabar, tugma bosilishi, botni boshlash yoki bloklash. Ularni ikki usulda olasiz: getUpdates (long polling) yoki webhook. Ikkalasi birga ishlamaydi. Batafsil.

chat_id

Xabar yuborish uchun foydalanuvchining chat_id'si kerak. Uni yangilanishdan olasiz: message.chat.id (shaxsiy chatda u message.from.id bilan bir xil). Bot faqat o'zini boshlagan va bloklamagan foydalanuvchilarga yoza oladi; boshqa har qanday id uchun javob bir xil: 400 Bad Request: chat not found. Guruh va kanallarning id'lari manfiy (masalan -4012345678) — chat id'lari.

Botga xos foydalanuvchi id'lari

Bot foydalanuvchining haqiqiy hisob id'sini hech qachon ko'rmaydi. Uning o'rniga shu botga xos psevdonim raqam (10–13 xonali) beriladi. Bitta odam ikki xil botda ikki xil id bilan ko'rinadi, shuning uchun botlar foydalanuvchilarni o'zaro solishtira olmaydi. Bitta bot uchun esa bu id doimiy: uni ma'lumotlar bazangizda kalit sifatida ishlatishingiz mumkin.

Maxfiylik modeli: bot nimani ko'radi

Bot ko'radiBot hech qachon ko'rmaydi
Ism, familiya, ochiq username, ilova tili; botga yozilgan xabarlar va fayllar; tugma bosilishlari; Start/bloklash holati.Telefon raqam, profil rasmi, bio, tug'ilgan kun, onlayn holat, kontaktlar, joylashuv, Davra, boshqa chatlar, qurilmalar, email, haqiqiy hisob id'si.
Telefon raqam yoki joylashuv — faqat foydalanuvchi request_contact / request_location tugmasini bosib, tasdiqlab yuborganda.Foydalanuvchi qidirish, ro'yxat yoki boshqa foydalanuvchilar haqida ma'lumot olish usuli yo'q.

To'liq ro'yxat: User turi va Maxfiylik va xavfsizlik.

Nega bot chatlari uchidan-uchiga shifrlanmagan

Zamin'dagi oddiy chatlar uchidan-uchiga shifrlangan: xabarlarni faqat suhbatdoshlarning telefonlari o'qiy oladi, server ham o'qiy olmaydi. Bot esa telefon emas — u sizning serveringizda ishlaydigan dastur va xabarlarni Bot API orqali oddiy JSON ko'rinishida oladi. Demak, server xabarni botga ochiq holda uzatishi kerak.

Shuning uchun bot chatlari serverda server kaliti bilan shifrlangan holda saqlanadi (at rest), lekin Zamin serveri va bot egasi ularni o'qiy oladi. Ilova har bir bot chatida "uchidan-uchiga shifrlanmagan" ogohlantirishini ko'rsatadi. Bot egasi sifatida foydalanuvchilarga shunga yarasha munosabatda bo'ling: faqat kerakli ma'lumotni saqlang.

Keyingi qadamlar

@ZaminBot qo'llanmasiBarcha buyruqlar va namunaviy suhbatlar.Bot API asoslariSo'rovlar, javoblar, xatolar va limitlar.TurlarMessage, User, Update va boshqalar.DarsliklarTo'liq Python kodi bilan 5 ta bot.