TelegramAccount: Telegram akkauntini Python'da MTProto orqali boshqarish

disconnect() ning taxallusi — SDK'ning boshqa klientlaridagi close() bilan bir xil nom bo'lishi uchun.

await tg.close() -> None

MTProto ulanishini ochadi va litsenziyani tekshiradi, lekin akkaunt avtorizatsiyasini tekshirmaydi — login oqimi ulanishni avtorizatsiyadan oldin talab qiladi. async with TelegramAccount(...) uni avtomatik chaqiradi.

await tg.connect() -> TelegramAccount

• ▸Ko'p metodlar ulanishni o'zi ochadi, lekin raw, export_session, join, create_channel, stats, contacts, resolve kabi ba'zilari ochiq ulanishni kutadi — async with ishlating yoki avval connect() chaqiring.
• ▸Ulangan klientda qayta chaqirish xavfsiz: hech narsa qilmaydi.

Ulanishni yopadi; async with blokidan chiqishda avtomatik chaqiriladi. Seans Telegram'da tugatilmaydi — saqlangan sessiya satri keyin ham ishlaydi.

await tg.disconnect() -> None

• ▸Seansni Telegram tomonida ham bekor qilish kerak bo'lsa — log_out().

Joriy sessiyani StringSession satri sifatida qaytaradi — keyingi safar TelegramAccount(session=...) bilan kodsiz ulanish uchun. Sinxron metod, lekin ochiq ulanishni talab qiladi.

tg.export_session() -> str

• ▸Satr ichida data-markaz manzili va avtorizatsiya kaliti bor — u akkauntga to'liq kirish beradi. Bazada shifrlab saqlang, log'ga chiqarmang.
• ▸Satr sizib chiqsa: log_out() yoki boshqa seansdan reset_session().

Klientni muhit o'zgaruvchilaridan yaratadi: TELEGRAM_API_ID, TELEGRAM_API_HASH va ixtiyoriy TELEGRAM_SESSION. Qo'shimcha argumentlar (license_key, proxy, device_model ...) konstruktorga uzatiladi.

TelegramAccount.from_env(**kwargs) -> TelegramAccount

• ▸TELEGRAM_SESSION bo'sh bo'lsa klient sessiyasiz yaratiladi — avval login oqimi (send_code → sign_in) kerak.
• ▸TELEGRAM_API_ID yo'q yoki musbat butun son bo'lmasa, TELEGRAM_API_HASH bo'sh bo'lsa — ConfigurationError.

Joriy sessiya akkauntga kirganmi — True yoki False. Saqlangan sessiya hali ishlayotganini tekshirish uchun qulay.

await tg.is_authorized() -> bool

• ▸Seans boshqa qurilmadan tugatilgan bo'lsa, qolgan metodlar AuthError beradi — akkauntni qayta ulash kerak.

ok = await tg.is_authorized()

Seansni Telegram'da tugatadi (auth.logOut) va ulanishni yopadi. Shundan keyin saqlangan sessiya satri ishlamaydi — qayta ulash uchun telefon va kod yana kerak.

await tg.log_out() -> bool

• ▸Faqat ulanishni yopish kerak bo'lsa (sessiya saqlanib qolsin) — disconnect().

await tg.log_out()

Boshqa qurilmadagi seansni sessions() dagi hash bo'yicha tugatadi (account.resetAuthorization).

await tg.reset_session(session_id: int) -> Any

• ▸Joriy seans kirganiga 24 soat bo'lmagan bo'lsa, Telegram boshqa seanslarni tugatishga ruxsat bermaydi (FRESH_RESET_AUTHORISATION_FORBIDDEN).

await tg.reset_session(session_hash)

Login 1-qadami: telefon raqamiga tasdiqlash kodini so'raydi va phone_code_hash hamda oraliq session satrini qaytaradi. Raqam xalqaro formatda beriladi; bo'shliq va chiziqlar avtomatik olib tashlanadi.

await tg.send_code(phone: str) -> dict

• ▸Kod SMS emas, shu akkaunt ochiq turgan Telegram ilovasiga kelishi mumkin — qayerga yuborilgani javobdagi type maydonida.
• ▸phone_code_hash faqat o'sha sessiya ichida yaroqli: qadamlar turli so'rovlarda bo'lsa, keyingi qadamni TelegramAccount(..., session=sent["session"]) bilan davom ettiring.
• ▸Sessiya allaqachon avtorizatsiyalangan bo'lsa kod yuborilmaydi va already_authorized: True qaytadi.

sent = await tg.send_code("+998901234567")

Akkauntdagi barcha faol seanslar (qurilmalar) ro'yxati — account.getAuthorizations. Har bir yozuvda qurilma, ilova, faollik vaqti va hash bor.

await tg.sessions() -> Any

• ▸hash — seansni reset_session() bilan tugatish uchun identifikator.

sessions = await tg.sessions()

Login 2-qadami: kelgan kod va phone_code_hash bilan kiradi. Muvaffaqiyatda authorized: True, doimiy session satri va user (id, username, phone, ism) qaytadi.

await tg.sign_in(
    phone: str,
    code: str,
    *,
    phone_code_hash: Optional[str] = None,
) -> dict

• ▸Akkauntda ikki bosqichli parol bo'lsa istisno emas, two_factor_required: True qaytadi — keyin sign_in_password() chaqiring.
• ▸Noto'g'ri yoki muddati o'tgan kod, yaroqsiz raqam yoki api_id/api_hash — tushunarli matnli AuthError.

result = await tg.sign_in("+998901234567", code="12345", phone_code_hash=sent["phone_code_hash"])

Login 3-qadami: ikki bosqichli (2FA) parol bilan kirishni yakunlaydi va sign_in() bilan bir xil shakldagi natija qaytaradi.

await tg.sign_in_password(password: str) -> dict

• ▸Parol serverga ochiq holda yuborilmaydi: Telegram SRP protokolidan foydalanadi, isbotni Telethon lokal hisoblaydi.
• ▸Noto'g'ri parol — AuthError. Parolni log'ga yozmang va saqlamang.

result = await tg.sign_in_password("mening-parolim")

Profil rasmlarini o'chiradi; photos berilmasa akkauntning barcha profil rasmlari o'chiriladi.

await tg.delete_profile_photos(photos: Optional[Sequence[Any]] = None) -> Any

• ▸Bittasini o'chirish uchun profile_photos() dan kerakli obyektni ro'yxat qilib bering — argumentsiz chaqiruv hammasini o'chiradi.

Joriy akkaunt (User): id, ism, username, telefon. Sessiya kimga tegishli ekanini aniqlash uchun.

await tg.me() -> Any

me = await tg.me()

Foydalanuvchi, guruh yoki kanalning profil rasmlari ro'yxati; standart holda o'zingizniki, 20 tagacha.

await tg.profile_photos(entity: Union[int, str, Any] = 'me', *, limit: int = 20) -> list

Yangi profil rasmini yuklaydi va o'rnatadi; fayl yo'li, baytlar yoki fayl obyekti qabul qilinadi.

await tg.set_profile_photo(file: Any) -> Any

Akkauntning ommaviy @username ini o'rnatadi; bo'sh satr uni olib tashlaydi.

await tg.set_username(username: str) -> Any

• ▸Username 5–32 belgi: lotin harflari, raqamlar va pastki chiziq.
• ▸Band bo'lsa Telegram USERNAME_OCCUPIED, noto'g'ri formatda USERNAME_INVALID qaytaradi — SDK'da ApiError.

Ism, familiya va bio (about) ni o'zgartiradi; berilmagan maydonlar o'zgarmaydi (account.updateProfile).

await tg.update_profile(
    *,
    first_name: Optional[str] = None,
    last_name: Optional[str] = None,
    about: Optional[str] = None,
) -> Any

• ▸Bio uzunligi cheklangan, Premium va oddiy akkauntlar uchun alohida (about_length_limit_* konfiguratsiyada).

Suhbatda "yozmoqda...", "rasm yubormoqda..." kabi holatni ko'rsatadi. Qiymatlar: typing, cancel, photo, video, record-video, audio, record-audio, document, location, contact, game.

await tg.action(entity: Union[int, str, Any], action: str = 'typing') -> Any

• ▸Holat 6 soniya amal qiladi; uzoqroq ko'rsatish uchun takrorlang yoki async with tg.client.action(entity, "typing"): ishlating.

await tg.action("@durov", "typing")

Suhbatni arxivga soladi (archived=True) yoki arxivdan qaytaradi (archived=False).

await tg.archive(entity: Union[int, str, Any], *, archived: bool = True) -> Any

Suhbatni ro'yxatdan olib tashlaydi: kanal va supergroup'dan chiqadi, oddiy guruhdan chiqib tarixni tozalaydi, shaxsiy chatda tarixni o'chiradi.

await tg.delete_dialog(entity: Union[int, str, Any], *, revoke: bool = False) -> Any

• ▸revoke=True — shaxsiy chat tarixi suhbatdoshda ham o'chadi; kanal va supergroup'ga ta'sir qilmaydi.

Xabarlarni ID bo'yicha o'chiradi. revoke=True (standart) — hamma uchun; False — shaxsiy chat va oddiy guruhda faqat o'zingizda.

await tg.delete_messages(
    entity: Union[int, str, Any],
    message_ids: Iterable[int],
    *,
    revoke: bool = True,
) -> Any

• ▸Supergroup va kanalda xabar har doim hamma uchun o'chadi; boshqalarning xabarini o'chirish uchun delete_messages admin huquqi kerak.
• ▸Xizmat xabarlarini o'chirib bo'lmaydi (MESSAGE_DELETE_FORBIDDEN → PermissionError).
• ▸O'chirish vaqti ham cheklanishi mumkin (revoke_time_limit, revoke_pm_time_limit).

await tg.delete_messages("me", [101, 102], revoke=True)

Suhbatlar ro'yxati — shaxsiy chatlar, guruhlar va kanallar, oxirgi faollik bo'yicha. Standart 50 ta; archived=True — faqat arxiv, folder — papka ID.

await tg.dialogs(
    *,
    limit: int = 50,
    archived: Optional[bool] = None,
    folder: Optional[int] = None,
) -> list

• ▸limit=None hammasini oladi, lekin katta akkauntda bu ko'p so'rov va flood xavfi — kerakli qismini oling.
• ▸Arxiv papkasining ID'si 1, qolgan chatlar 0 da.

dialogs = await tg.dialogs(limit=50)

Yuborilgan xabarning matni, media yoki tugmalarini tahrirlaydi. Odatda faqat o'z xabaringiz; kanal postlari — edit_messages admin huquqi bilan.

await tg.edit_message(
    entity: Union[int, str, Any],
    message_id: int,
    text: Optional[str] = None,
    *,
    file: Optional[Any] = None,
    parse_mode: Optional[str] = 'md',
    link_preview: bool = True,
    buttons: Optional[Any] = None,
) -> Any

• ▸Tahrirlash vaqti cheklangan: juda eski xabarda MESSAGE_EDIT_TIME_EXPIRED (chegara — konfiguratsiyadagi edit_time_limit).
• ▸Matn o'zgarmagan bo'lsa Telegram MESSAGE_NOT_MODIFIED qaytaradi.

await tg.edit_message("me", message_id, "Tahrirlangan matn")

Xabarlarni from_entity dan to_entity ga uzatadi (argumentlar tartibi: qayerga, ID'lar, qayerdan). drop_author=True — asl muallif ko'rsatilmaydi, schedule — rejalashtirish.

await tg.forward_messages(
    to_entity: Union[int, str, Any],
    message_ids: Iterable[int],
    from_entity: Union[int, str, Any],
    *,
    silent: bool = False,
    drop_author: bool = False,
    schedule: Optional[datetime.datetime] = None,
) -> Any

• ▸Uzatish taqiqlangan (himoyalangan) chatdan uzatib bo'lmaydi — CHAT_FORWARDS_RESTRICTED.
• ▸Bir chaqiruvda uzatiladigan xabarlar soni cheklangan (forwarded_count_max).

await tg.forward_messages("me", [42], "@kanal", drop_author=True)

Suhbatni o'qilgan deb belgilaydi; message berilsa — o'sha xabargacha.

await tg.mark_read(
    entity: Union[int, str, Any],
    *,
    message: Optional[Any] = None,
) -> Any

await tg.mark_read("@guruh")

Bitta xabarni ID bo'yicha oladi; topilmasa istisno emas, None qaytaradi.

await tg.message(entity: Union[int, str, Any], message_id: int) -> Any

msg = await tg.message("@kanal", 42)

msg = await tg.message("@kanal", 42)
data = await tg.download(msg)

Suhbat tarixini o'qiydi — Bot API'da bunday metod yo'q. Yangidan eskiga qarab; search, from_user, filter, min_id/max_id bilan saralanadi, ids bilan aniq xabarlar olinadi.

await tg.messages(
    entity: Union[int, str, Any],
    *,
    limit: int = 50,
    offset_id: int = 0,
    min_id: int = 0,
    max_id: int = 0,
    search: Optional[str] = None,
    from_user: Union[int, str, Any, NoneType] = None,
    reverse: bool = False,
    ids: Union[int, Sequence[int], NoneType] = None,
    filter: Optional[Any] = None,
) -> list

• ▸Sahifalash: keyingi sahifa uchun offset_id ga oldingi sahifadagi eng kichik message.id ni bering; reverse=True — eskidan yangiga.
• ▸ids berilsa ro'yxat uzunligi saqlanadi — topilmagan xabar o'rnida None.

history = await tg.messages("@durov", limit=50)

Suhbat bildirishnomalarini o'chiradi. until — unix vaqt (soniyada); berilmasa amalda abadiy.

await tg.mute(
    entity: Union[int, str, Any],
    *,
    until: Union[int, datetime.datetime, NoneType] = None,
) -> Any

• ▸until=0 ham abadiy o'chirish sifatida talqin qilinadi — qayta yoqish uchun unmute().

Suhbatni chatlar ro'yxati tepasiga qadaydi yoki pinned=False bilan qadashni olib tashlaydi.

await tg.pin_dialog(entity: Union[int, str, Any], *, pinned: bool = True) -> Any

• ▸Qadalgan suhbatlar soni cheklangan (Premium bo'lmagan akkaunt uchun dialogs_pinned_limit_default).

Xabarni suhbatda qadaydi; standart holda bildirishnomasiz (notify=False). pm_oneside=True — shaxsiy chatda faqat o'zingizda qadaladi.

await tg.pin_message(
    entity: Union[int, str, Any],
    message_id: int,
    *,
    notify: bool = False,
    pm_oneside: bool = False,
) -> Any

• ▸Guruh va kanalda qadash huquqi kerak — aks holda CHAT_ADMIN_REQUIRED yoki PIN_RESTRICTED.

await tg.pin_message("me", 42, notify=False)

Xabarga emoji reaksiya qo'yadi; emoji=None reaksiyani olib tashlaydi, big=True katta animatsiya ko'rsatadi.

await tg.react(
    entity: Union[int, str, Any],
    message_id: int,
    emoji: Optional[str] = None,
    *,
    big: bool = False,
) -> Any

• ▸Adminlar chatda ruxsat etilgan reaksiyalarni cheklashi mumkin (chat_full() dagi available_reactions); ruxsatsiz emoji — REACTION_INVALID.

await tg.react("@guruh", 42, "👍")

Suhbatdagi rejalashtirilgan, hali yuborilmagan xabarlar — send_message(..., schedule=...) yoki send_file(..., schedule=...) bilan qo'yilganlar.

await tg.scheduled(entity: Union[int, str, Any]) -> Any

scheduled = await tg.scheduled("me")

Shaxsiy chat, guruh yoki kanalga xabar yuboradi; entity — @username, raqamli ID, t.me/... havola yoki "me" (Saqlangan xabarlar). Javob, fayl, tugmalar, jim yuborish va kanal postiga izoh (comment_to) qo'llanadi.

await tg.send_message(
    entity: Union[int, str, Any],
    message: str = '',
    *,
    reply_to: Optional[int] = None,
    parse_mode: Optional[str] = 'md',
    link_preview: bool = True,
    file: Optional[Any] = None,
    silent: bool = False,
    schedule: Optional[datetime.datetime] = None,
    buttons: Optional[Any] = None,
    formatting_entities: Optional[list] = None,
    comment_to: Optional[int] = None,
) -> Any

• ▸schedule=datetime — xabar Telegram serverida rejalashtiriladi va vaqti kelganda Telegram o'zi yuboradi; ilovangiz ishlab turishi shart emas.
• ▸Standart parse_mode="md": foydalanuvchi matnidagi **, __, ~~ yoki [matn](url) formatlashga aylanadi. Xom matn uchun parse_mode=None.
• ▸So'ralmagan ommaviy xabarlar spam hisoblanadi: Telegram API'dan spam uchun foydalangan akkaunt butunlay bloklanadi.

await tg.send_message("@mening_guruhim", "Salom!", silent=True)

So'rovnoma yoki viktorina (quiz=True) yuboradi: options — javob variantlari, multiple — bir nechta tanlov, public — kim ovoz bergani ko'rinadi.

await tg.send_poll(
    entity: Union[int, str, Any],
    question: str,
    options: Sequence[str],
    *,
    multiple: bool = False,
    quiz: bool = False,
    correct: Optional[int] = None,
    public: bool = False,
) -> Any

• ▸Viktorinada correct (to'g'ri javob indeksi, 0 dan) majburiy — bermasangiz SDK so'rovni yubormasdan ConfigurationError beradi.

await tg.send_poll("@guruh", "Qaysi kun?", ["Dushanba", "Juma"], multiple=False)

Suhbat bildirishnomalarini qayta yoqadi.

await tg.unmute(entity: Union[int, str, Any]) -> Any

Qadalgan xabarni ochadi; message_id berilmasa suhbatdagi barcha qadalgan xabarlar ochiladi.

await tg.unpin_message(
    entity: Union[int, str, Any],
    message_id: Optional[int] = None,
) -> Any

await tg.unpin_message("me", 42)

Xabardagi media faylni yuklab oladi: standart holda bytes qaytaradi; file ga yo'l bersangiz diskka yozadi va yo'lni qaytaradi.

await tg.download(message: Any, *, file: Any = <class 'bytes'>) -> Any

msg = await tg.message("@kanal", 42)
data = await tg.download(msg)

Bir nechta faylni bitta albom (media group) sifatida yuboradi; caption va send_file() ning boshqa parametrlari qo'llanadi.

await tg.send_album(
    entity: Union[int, str, Any],
    files: Sequence[Any],
    *,
    caption: Optional[str] = None,
    **kwargs: Any,
) -> Any

• ▸Telegram bitta albomga 10 tagacha media qabul qiladi; ko'proq fayl berilsa Telethon ularni 10 tadan bir nechta albomga bo'ladi.

Rasm, video, hujjat, ovozli xabar yoki dumaloq video yuboradi; file — yo'l, baytlar, fayl obyekti, URL yoki upload() natijasi. caption, reply_to, silent, schedule qo'llanadi.

await tg.send_file(
    entity: Union[int, str, Any],
    file: Any,
    *,
    caption: Optional[str] = None,
    force_document: bool = False,
    voice_note: bool = False,
    video_note: bool = False,
    silent: bool = False,
    reply_to: Optional[int] = None,
    thumb: Optional[Any] = None,
    attributes: Optional[list] = None,
    schedule: Optional[datetime.datetime] = None,
    parse_mode: Optional[str] = 'md',
) -> Any

• ▸Faylni asl ko'rinishida (hujjat sifatida) yetkazish uchun force_document=True.
• ▸voice_note=True — ovozli xabar, video_note=True — dumaloq video sifatida yuboriladi.

await tg.send_file("me", "photo.jpg", caption="Rasm")

Faylni oldindan Telegram serveriga yuklaydi va natijani qaytaradi; uni keyin send_file() ga berish mumkin (filename — ko'rinadigan fayl nomi).

await tg.upload(file: Any, *, filename: Optional[str] = None) -> Any

• ▸Yuklangan qismlar serverda vaqtincha — bir necha daqiqadan bir necha soatgacha saqlanadi, shuning uchun natijani tez ishlating.

Story joylash mumkinmi — joylashdan oldingi tekshiruv (stories.canSendStory). Muvaffaqiyatda bo'sh story «slot»lari soni (count) qaytadi; Telegram hujjati aynan shu chaqiruvni story yuborishdan oldin talab qiladi.

await tg.can_send_story(entity: Union[int, str, Any] = 'me') -> Any

• ▸entity="me" — o'z nomingizdan; kanal yoki supergroup bersangiz — o'sha kanal nomidan.
• ▸Xatolar SDK tilida: PREMIUM_ACCOUNT_REQUIRED — foydalanuvchida Premium yo'q; CHAT_ADMIN_REQUIRED — kanalda post_stories huquqi yo'q (PermissionError); BOOSTS_REQUIRED — kanalga yetarli «boost» berilmagan; STORIES_TOO_MUCH — faol story'lar chegarasi.
• ▸Haftalik va oylik chegara (STORY_SEND_FLOOD_WEEKLY / STORY_SEND_FLOOD_MONTHLY) RateLimitError bo'lib keladi, kutish soniyalari retry_after da.
• ▸Bu kafolat emas: tekshiruv bilan send_story() orasida holat o'zgarsa (masalan boshqa qurilmadan story joylansa), o'sha xatolar joylash paytida qaytadi.

check = await tg.can_send_story("me")

Bitta story'ni yoki ro'yxatdagi bir nechtasini o'chiradi (stories.deleteStories) va haqiqatan o'chirilgan ID'lar ro'yxatini qaytaradi.

await tg.delete_story(
    entity: Union[int, str, Any],
    story_id: Union[int, Iterable[int]],
) -> Any

• ▸Faol, profilga qadalgan va arxivdagi story — hammasi o'chadi; qaytarib bo'lmaydi.
• ▸Mavjud bo'lmagan ID xato emas — u shunchaki javobdagi ro'yxatga kirmaydi.

await tg.delete_story("me", [42, 43])

Joylangan story'ni tahrirlaydi (stories.editStory): faqat siz bergan maydonlar yuboriladi, qolgani o'zgarmaydi. Masalan caption ni almashtirish yoki maxfiylikni toraytirish uchun.

await tg.edit_story(
    entity: Union[int, str, Any],
    story_id: int,
    *,
    file: Optional[Any] = None,
    caption: Optional[str] = None,
    privacy: Union[str, Sequence[Any], NoneType] = None,
    allow: Optional[Sequence[Union[int, str, Any]]] = None,
    deny: Optional[Sequence[Union[int, str, Any]]] = None,
    photo: Optional[bool] = None,
    thumb: Optional[Any] = None,
    parse_mode: Optional[str] = None,
    entities: Optional[list] = None,
    media_areas: Optional[list] = None,
) -> Any

• ▸privacy bu yerda standart None (send_story dan farqli — u yerda maxfiylik majburiy va "everyone"): tegmasangiz story'ning joriy maxfiyligi saqlanadi.
• ▸Hech qanday maydon berilmasa ConfigurationError — bo'sh tahrir Telegram uchun ma'nosiz so'rov.
• ▸file berilsa media butunlay qayta yuklanadi (o'sha 30 MB chegarasi bilan): Telegram hujjatiga ko'ra fayl atributlari mediaga «kavsharlangan», ularni boshqacha yo'l bilan o'zgartirib bo'lmaydi.

await tg.edit_story("me", 42, caption="Tahrirlangan matn")

Story joylaydi (stories.sendStory): entity — kim nomidan ("me" yoki kanal/supergroup), file — vertikal rasm yoki video. Javob — Updates, ichida yangi story id si (updateStoryID).

await tg.send_story(
    entity: Union[int, str, Any],
    file: Any,
    *,
    caption: Optional[str] = None,
    period: Union[int, datetime.timedelta, NoneType] = None,
    privacy: Union[str, Sequence[Any], NoneType] = 'everyone',
    allow: Optional[Sequence[Union[int, str, Any]]] = None,
    deny: Optional[Sequence[Union[int, str, Any]]] = None,
    pinned: bool = False,
    noforwards: bool = False,
    photo: Optional[bool] = None,
    thumb: Optional[Any] = None,
    parse_mode: Optional[str] = None,
    entities: Optional[list] = None,
    media_areas: Optional[list] = None,
    albums: Optional[Sequence[int]] = None,
) -> Any

• ▸Telegram talabi: foydalanuvchi nomidan joylash uchun akkauntda **Telegram Premium** bo'lishi kerak (aks holda PREMIUM_ACCOUNT_REQUIRED); kanal nomidan — post_stories huquqli admin bo'lish va kanalga yetarli «boost» berilgan bo'lishi kerak. Shuning uchun avval can_send_story(entity) ni chaqiring — xato fayl yuklangandan keyin emas, oldin ko'rinadi.
• ▸file — yo'l, baytlar, fayl obyekti yoki tayyor InputFile; ko'pi bilan 30 MB va bu chegara mahalliy tekshiriladi. Tur kengaytma bo'yicha aniqlanadi (.jpg/.png — rasm, qolgani — video), majburlash uchun photo=True/False.
• ▸period — story necha soniyadan keyin arxivga tushadi va faqat to'rt qiymat qabul qilinadi: 21600 (6 soat), 43200 (12 soat), 86400 (24 soat), 172800 (48 soat); timedelta ham bo'ladi. Premium'siz akkauntda faqat 86400 ishlaydi, qolganlarini Telegram rad etadi. Berilmasa maydon yuborilmaydi va Telegram 24 soat qo'yadi.
• ▸privacy: "everyone" (standart), "contacts", "close_friends" (ro'yxat Telegram ilovasida boshqariladi) yoki "selected" — oxirgisida allow majburiy. deny istisnolar ro'yxati va qoidalar oxiriga qo'shiladi («kontaktlar, lekin falonchi emas»).
• ▸pinned=True — muddat tugagach story profilda qoladi; noforwards=True — uzatish va saqlashni taqiqlaydi.
• ▸caption uzunligi chegarasi Telegram config'idan keladi va hujjatda raqam bilan berilmagan, shuning uchun SDK uni tekshirmaydi. parse_mode berilmasa matn toza holda ketadi: story'da formatlash akkaunt config'iga bog'liq, hamma akkauntda ishlamaydi.
• ▸Nisbat va davomiylikni Telegram hujjatda raqam bilan bermaydi — SDK ularni tekshirmaydi, vertikal bo'lmagan media ilovalarda noto'g'ri qirqiladi.

await tg.send_story("me", "story.mp4", caption="Salom!", period=86400,
                    privacy="contacts", pinned=False)

Peer'ning hozir faol story'larini qaytaradi (stories.getPeerStories): stories.PeerStories ichida StoryItem lar. ids=[...] berilsa aynan o'sha story'lar so'raladi (stories.getStoriesByID).

await tg.stories(
    entity: Union[int, str, Any] = 'me',
    *,
    ids: Union[int, Iterable[int], NoneType] = None,
) -> Any

• ▸Ba'zi elementlar StoryItemSkipped bo'lib kelishi mumkin — Telegram joyni tejab to'liq ma'lumotni yubormaydi; o'shalarni stories(entity, ids=[...]) bilan alohida so'rang.
• ▸Muddati tugagan story'lar bu yerda yo'q: ular arxivda (stories.getStoriesArchive) yoki profilga qadalganlar orasida (stories.getPinnedStories) — ular uchun raw() ishlatiladi.

items = await tg.stories("me")

Qaysi kanal va supergroup nomidan story joylash mumkinligini qaytaradi (stories.getChatsToSend). Kabinet yoki ilovada «kim nomidan joylaymiz?» ro'yxatini ko'rsatish uchun.

await tg.story_targets() -> Any

• ▸Ro'yxatda bo'lish hali «joylasa bo'ladi» degani emas: boost va chegaralar can_send_story(entity) da tekshiriladi, shuning uchun uni baribir chaqiring.

targets = await tg.story_targets()

Telefon raqami bo'yicha kontakt qo'shadi (contacts.importContacts). Raqam Telegram'da bo'lsa, foydalanuvchi javobdagi imported va users ichida qaytadi.

await tg.add_contact(phone: str, first_name: str, *, last_name: str = '') -> Any

• ▸Raqam topilmasa ham istisno chiqmaydi — imported bo'sh bo'ladi, shuning uchun natijani tekshiring.
• ▸retry_contacts — tizim cheklovi sabab hozir import qilinmagan kontaktlar; ularni keyinroq qayta qo'shish kerak.

await tg.add_contact("+998901234567", "Ali", last_name="Valiyev")

Foydalanuvchini bloklaydi (contacts.block); qaytarish uchun unblock().

await tg.block(user: Union[int, str, Any]) -> Any

await tg.block("@spam_bot")
await tg.unblock("@spam_bot")

Bloklangan foydalanuvchilar ro'yxati, standart holda 100 tagacha.

await tg.blocked(*, limit: int = 100) -> Any

blocked = await tg.blocked(limit=100)

Siz va ko'rsatilgan foydalanuvchi birga a'zo bo'lgan guruh va kanallar, standart 100 tagacha.

await tg.common_chats(user: Union[int, str, Any], *, limit: int = 100) -> Any

chats = await tg.common_chats("@foydalanuvchi")

Akkauntning kontaktlar ro'yxati (contacts.getContacts): kontakt yozuvlari va ularning users obyektlari.

await tg.contacts() -> Any

contacts = await tg.contacts()

Foydalanuvchini kontaktlar ro'yxatidan o'chiradi.

await tg.delete_contact(user: Union[int, str, Any]) -> Any

await tg.delete_contact("@foydalanuvchi")

@username, raqamli ID, t.me/... havola yoki telefon raqamini Telegram obyektiga (User, Chat, Channel) aylantiradi. Boshqa metodlar ham ichkarida shuni ishlatadi.

await tg.entity(entity: Union[int, str, Any]) -> Any

• ▸Raqamli ID faqat sessiya xotirasidagi obyektlar uchun ishlaydi (masalan, dialogs() yoki participants() dan keyin) — sessiya satri bu keshni saqlamaydi. Topilmasa NotFoundError.

@username ni to'g'ridan-to'g'ri Telegram'dan so'raydi (contacts.resolveUsername); @ bilan ham, usiz ham ishlaydi. Javobda peer, users va chats.

await tg.resolve(username: str) -> Any

• ▸Keshga qaraydigan entity() dan farqli, har chaqiruv serverga so'rov — takroriy qidiruvlarda entity() afzal.

Foydalanuvchini blokdan chiqaradi.

await tg.unblock(user: Union[int, str, Any]) -> Any

await tg.block("@spam_bot")
await tg.unblock("@spam_bot")

Foydalanuvchi haqida to'liq ma'lumot (users.getFullUser): bio, umumiy guruhlar soni va boshqa profil maydonlari.

await tg.user_full(user: Union[int, str, Any]) -> Any

user = await tg.user_full("@durov")

Guruh yoki kanal haqida to'liq ma'lumot: tavsif, a'zolar soni, taklif havolasi, bog'langan muhokama guruhi, kutilayotgan so'rovlar. Supergroup/kanal uchun channels.getFullChannel, oddiy guruh uchun messages.getFullChat.

await tg.chat_full(entity: Union[int, str, Any]) -> Any

• ▸Foydali bayroqlar full_chat ichida: can_view_stats — statistika ochiqmi, can_view_participants — a'zolar ro'yxatini ko'ra olasizmi, slowmode_seconds — joriy sekin rejim.

info = await tg.chat_full("@kanal")

Kanal (broadcast=True, standart) yoki supergroup (broadcast=False) yaratadi; about — tavsif.

await tg.create_channel(title: str, *, about: str = '', broadcast: bool = True) -> Any

• ▸Yangi kanal ommaviy username'siz, ya'ni yopiq holda yaratiladi.

channel = await tg.create_channel("Yangiliklar", about="Kompaniya yangiliklari")

Guruh yaratadi: megagroup=True (standart) — supergroup, megagroup=False — users bilan oddiy guruh.

await tg.create_group(
    title: str,
    users: Sequence[Union[int, str, Any]],
    *,
    megagroup: bool = True,
    about: str = '',
) -> Any

• ▸megagroup=True bo'lsa users guruhga qo'shilmaydi — a'zolarni keyin invite() bilan qo'shing. Oddiy guruhda about qo'llanmaydi.
• ▸Oddiy guruh 200 a'zogacha, supergroup 200 000 gacha sig'adi.

group = await tg.create_group("Playground guruhi", ["@do'stim"], megagroup=True)

Guruh yoki kanalni hamma uchun butunlay o'chiradi — a'zolar va tarix qaytarilmaydi. Yaratuvchi huquqi kerak, aks holda PermissionError.

await tg.delete_chat(entity: Union[int, str, Any]) -> Any

• ▸1000 dan ortiq a'zoli kanal yoki supergroup'ni API orqali o'chirib bo'lmaydi — CHANNEL_TOO_LARGE.

await tg.delete_chat("@mening_kanalim")

Guruh yoki kanalga qo'shiladi: ommaviy @username ham, t.me/+... yoki t.me/joinchat/... taklif havolasi ham qabul qilinadi — kerakli TL so'rovini SDK o'zi tanlaydi.

await tg.join(entity: Union[str, int, Any]) -> Any

• ▸Havola admin tasdig'ini talab qilsa Telegram INVITE_REQUEST_SENT qaytaradi — bu so'rov yuborildi degani (SDK'da ApiError).
• ▸Akkaunt a'zo bo'lishi mumkin bo'lgan kanal va supergroup'lar soni cheklangan — oshsa CHANNELS_TOO_MUCH.

await tg.join("@kanal")

Guruh yoki kanaldan chiqadi; oddiy guruhda chat tarixi ham sizda tozalanadi.

await tg.leave(entity: Union[int, str, Any]) -> Any

await tg.leave("@kanal")

Guruh yoki kanal tavsifini (about) o'zgartiradi.

await tg.set_about(entity: Union[int, str, Any], about: str) -> Any

• ▸Tavsif uzunligi cheklangan — oshsa CHAT_ABOUT_TOO_LONG, matn o'zgarmagan bo'lsa CHAT_ABOUT_NOT_MODIFIED.

Guruhning barcha a'zolari uchun standart ruxsatlarni o'rnatadi (masalan, hammaga yozishni yopish: send_messages=False). restrict() dagi kabi False — taqiqlash.

await tg.set_default_permissions(entity: Union[int, str, Any], **rights: bool) -> Any

• ▸view_messages bu yerda ishlatilmaydi — u faqat alohida a'zoni taqiqlash uchun.
• ▸Telethon bu amalni faqat supergroup va kanal uchun bajaradi; oddiy guruhda SDK NotFoundError beradi.

Guruh yoki kanal rasmini fayldan (yo'l, baytlar yoki fayl obyekti) yuklab o'rnatadi.

await tg.set_photo(entity: Union[int, str, Any], file: Any) -> Any

await tg.set_photo("@guruh", "logo.png")

Supergroup'da sekin rejimni yoqadi: har bir a'zo seconds soniyada bitta xabar yubora oladi; 0 — o'chirish.

await tg.set_slowmode(entity: Union[int, str, Any], seconds: int = 0) -> Any

• ▸Faqat supergroup uchun. Telegram qabul qilmaydigan davomiylik berilsa — SECONDS_INVALID.

await tg.set_title("@guruh", "Yangi nom")
await tg.set_slowmode("@guruh", 30)

Guruh yoki kanal nomini o'zgartiradi; change_info huquqi kerak.

await tg.set_title(entity: Union[int, str, Any], title: str) -> Any

await tg.set_title("@guruh", "Yangi nom")
await tg.set_slowmode("@guruh", 30)

Faqat adminlar ro'yxati, limit cheklovisiz; har bir foydalanuvchining participant maydonida roli va huquqlari.

await tg.admins(entity: Union[int, str, Any]) -> list

admins = await tg.admins("@guruh")

A'zoni chiqarib, qaytib kirishini taqiqlaydi. until (datetime) — muddatli taqiq; berilmasa abadiy.

await tg.ban(
    entity: Union[int, str, Any],
    user: Union[int, str, Any],
    *,
    until: Optional[datetime.datetime] = None,
) -> Any

• ▸366 kundan uzun yoki 30 soniyadan qisqa muddat Telegram tomonidan abadiy deb hisoblanadi.
• ▸Supergroup va kanalda ishlaydi (ban_users huquqi kerak); oddiy guruhda — kick().

await tg.ban("@guruh", "@foydalanuvchi")

Chatdan chiqarib yuborilgan (taqiqlangan) a'zolar, standart holda 100 tagacha.

await tg.banned(entity: Union[int, str, Any]) -> list

• ▸Faqat cheklangan (restricted) a'zolar kerak bo'lsa: participants(entity, filter=tg.tl().types.ChannelParticipantsBanned(q="")).

banned = await tg.banned("@guruh")

Adminlik huquqlarini olib, foydalanuvchini oddiy a'zoga qaytaradi.

await tg.demote(entity: Union[int, str, Any], user: Union[int, str, Any]) -> Any

await tg.demote("@guruh", "@foydalanuvchi")

Foydalanuvchilarni guruh yoki kanalga qo'shadi: supergroup va kanalda bitta so'rov bilan, oddiy guruhda bittalab.

await tg.invite(
    entity: Union[int, str, Any],
    users: Sequence[Union[int, str, Any]],
) -> Any

• ▸Maxfiylik sozlamasi ruxsat bermasa USER_PRIVACY_RESTRICTED (PermissionError) — bunday odamga taklif havolasini yuboring.
• ▸Supergroup/kanal javobidagi missing_invitees — qo'shilmay qolgan foydalanuvchilar.
• ▸Notanish odamlarni ommaviy qo'shish spam hisoblanadi: Telegram API'dan spam uchun foydalangan akkaunt butunlay bloklanadi.

await tg.invite("@guruh", ["@foydalanuvchi"])

A'zoni chatdan chiqaradi, lekin taqiqlamaydi — u havola orqali qaytib kira oladi. Butunlay taqiqlash uchun ban().

await tg.kick(entity: Union[int, str, Any], user: Union[int, str, Any]) -> Any

• ▸Supergroup va kanalda Telethon buni "taqiqlash + darhol taqiqni olish" orqali bajaradi.

await tg.kick("@guruh", "@foydalanuvchi")

A'zoga xabar yozishni taqiqlaydi — restrict(send_messages=False) ning qisqartmasi; until bilan muddatli.

await tg.mute_member(
    entity: Union[int, str, Any],
    user: Union[int, str, Any],
    *,
    until: Optional[datetime.datetime] = None,
) -> Any

Guruh yoki kanal a'zolari ro'yxati — Bot API'da bunday metod yo'q. search — ism yoki username bo'yicha, filter — adminlar, botlar, taqiqlanganlar va h.k., limit=None — hammasi.

await tg.participants(
    entity: Union[int, str, Any],
    *,
    limit: Optional[int] = 100,
    search: Optional[str] = None,
    aggressive: bool = False,
    filter: Optional[Any] = None,
) -> list

• ▸Kanal obunachilari uchun admin huquqi kerak (CHAT_ADMIN_REQUIRED → PermissionError); supergroup'da ro'yxat yashirilgan bo'lishi mumkin — chat_full() dagi can_view_participants ni tekshiring.
• ▸aggressive parametri Telethon'ning joriy versiyalarida hech narsa qilmaydi — orqaga moslik uchun qoldirilgan.
• ▸Olingan ro'yxatga so'ralmagan xabar yuborish yoki odamlarni boshqa chatlarga ommaviy qo'shish spam hisoblanadi va akkaunt bloklanishiga olib keladi.

members = await tg.participants("@guruh", limit=200)

Bitta a'zoning chatdagi holati va huquqlari: egami, adminmi, cheklanganmi, qaysi amallarga ruxsati bor (Telethon ParticipantPermissions).

await tg.permissions(entity: Union[int, str, Any], user: Union[int, str, Any]) -> Any

rights = await tg.permissions("@guruh", "@foydalanuvchi")

A'zoni admin qiladi; har bir huquq alohida bayroq (delete_messages, ban_users, pin_messages ...), title — admin unvoni. add_admins standart holda False, ya'ni yangi admin boshqalarni admin qila olmaydi.

await tg.promote(
    entity: Union[int, str, Any],
    user: Union[int, str, Any],
    *,
    title: Optional[str] = None,
    change_info: bool = True,
    post_messages: bool = True,
    edit_messages: bool = True,
    delete_messages: bool = True,
    ban_users: bool = True,
    invite_users: bool = True,
    pin_messages: bool = True,
    add_admins: bool = False,
    manage_call: bool = True,
    anonymous: bool = False,
) -> Any

• ▸Oddiy guruhda alohida huquqlar yo'q — foydalanuvchi shunchaki admin bo'ladi.
• ▸anonymous=True — admin a'zolar ro'yxatida ko'rinmaydi va o'z akkaunti nomidan yozolmaydi.

await tg.promote("@guruh", "@foydalanuvchi", title="Moderator", ban_users=True)

A'zoning alohida huquqlarini cheklaydi: xabar, media, stiker, GIF, havola, so'rovnoma va h.k. Diqqat: False — taqiqlash, True — ruxsat; until — muddat.

await tg.restrict(
    entity: Union[int, str, Any],
    user: Union[int, str, Any],
    *,
    until: Optional[datetime.datetime] = None,
    send_messages: bool = True,
    send_media: bool = True,
    send_stickers: bool = True,
    send_gifs: bool = True,
    send_games: bool = True,
    send_inline: bool = True,
    embed_links: bool = True,
    send_polls: bool = True,
    change_info: bool = True,
    invite_users: bool = True,
    pin_messages: bool = True,
    embed_link_previews: bool = True,
) -> Any

• ▸Faqat supergroup'da: oddiy guruh a'zolariga alohida cheklov qo'yib bo'lmaydi (SDK NotFoundError beradi).
• ▸Berilmagan parametr True hisoblanadi — har chaqiruv huquqlarning to'liq to'plamini qayta yozadi, avvalgi cheklovlar saqlanmaydi.

await tg.restrict("@guruh", "@foydalanuvchi", send_messages=False)

Taqiq va cheklovlarni olib tashlaydi. Foydalanuvchi avtomatik qaytmaydi — o'zi qo'shilishi yoki qayta taklif qilinishi kerak.

await tg.unban(entity: Union[int, str, Any], user: Union[int, str, Any]) -> Any

await tg.unban("@guruh", "@foydalanuvchi")

Qo'shilish so'rovini tasdiqlaydi (approved=True) yoki rad etadi (approved=False).

await tg.approve_join_request(
    entity: Union[int, str, Any],
    user: Union[int, str, Any],
    *,
    approved: bool = True,
) -> Any

await tg.approve_join_request("@guruh", 123456789, approved=True)

Qo'shimcha taklif havolasi yaratadi: title (faqat adminlarga ko'rinadi), expire_date, usage_limit — maksimal qo'shilishlar soni, request_needed — har bir qo'shilish uchun admin tasdig'i.

await tg.create_invite_link(
    entity: Union[int, str, Any],
    *,
    title: Optional[str] = None,
    expire_date: Optional[datetime.datetime] = None,
    usage_limit: Optional[int] = None,
    request_needed: bool = False,
) -> Any

• ▸request_needed=True bilan kelgan so'rovlar join_requests() da ko'rinadi va approve_join_request() bilan hal qilinadi.

link = await tg.create_invite_link("@guruh", title="Reklama", usage_limit=100)

Chat uchun cheklovsiz yangi taklif havolasini yaratadi (messages.exportChatInvite); havola javobning link maydonida.

await tg.invite_link(entity: Union[int, str, Any]) -> Any

• ▸Har chaqiruv yangi qo'shimcha havola yaratadi, mavjudlari bekor qilinmaydi. Chatning joriy havolasi — chat_full() dagi full_chat.exported_invite.
• ▸Muddat, limit yoki admin tasdig'i kerak bo'lsa — create_invite_link().

link = await tg.invite_link("@guruh")

Admin tasdig'ini kutayotgan qo'shilish so'rovlari (messages.getChatInviteImporters), standart 50 tagacha; javobda importers va users.

await tg.join_requests(entity: Union[int, str, Any], *, limit: int = 50) -> Any

requests = await tg.join_requests("@guruh")

Taklif havolasini bekor qiladi — u orqali endi qo'shilib bo'lmaydi; link — to'liq havola.

await tg.revoke_invite_link(entity: Union[int, str, Any], link: str) -> Any

• ▸Bekor qilingan havola haqidagi ma'lumot adminlar uchun saqlanib qoladi.

await tg.revoke_invite_link("@guruh", "https://t.me/+AbCdEf")

Bitta suhbat ichida matn bo'yicha qidiradi; from_user bilan faqat bir foydalanuvchi xabarlari. messages(search=...) ning qisqartmasi.

await tg.search(
    entity: Union[int, str, Any],
    query: str,
    *,
    limit: int = 50,
    from_user: Union[int, str, Any, NoneType] = None,
) -> list

found = await tg.search("@guruh", "narx", limit=50)
everywhere = await tg.search_global("socialift")

Siz a'zo bo'lgan barcha suhbatlar bo'yicha xabar qidiradi (messages.searchGlobal) va xom TL javobini (messages, chats, users) qaytaradi.

await tg.search_global(query: str, *, limit: int = 50) -> Any

• ▸Faqat birinchi sahifa (limit ta) qaytadi; davomi uchun raw() bilan offset_rate, offset_peer, offset_id bering.

found = await tg.search("@guruh", "narx", limit=50)
everywhere = await tg.search_global("socialift")

Kanal statistikasi (stats.getBroadcastStats): obunachilar, post ko'rishlari, ulashishlar va o'sish grafiklari. Kanal adminlari uchun.

await tg.stats(entity: Union[int, str, Any]) -> Any

• ▸Statistika faqat ma'lum hajmdagi kanallarda ochiq; chegara server sozlamasi — chat_full() dagi full_chat.can_view_stats bilan tekshiring.
• ▸Telegram bu so'rovni kanalning stats_dc data-markaziga yuborishni talab qiladi, SDK esa joriy markazga yuboradi — STATS_MIGRATE xatosi chiqishi mumkin. Bunda va supergroup statistikasi uchun await tg.client.get_stats("@kanal") ishlating: Telethon markazni o'zi tanlaydi.

stats = await tg.stats("@kanal")

Telethon'ning istalgan TL so'rovini (functions.*Request) yuboradi va xatolarni SDK ierarxiyasiga (RateLimitError, AuthError, PermissionError, NotFoundError) o'giradi. SDK o'ramagan imkoniyatlar uchun.

await tg.raw(request: Any) -> Any

• ▸So'rov maydonlariga @username yoki ID berish mumkin — Telethon ularni kerakli Input* turiga o'zi aylantiradi.
• ▸Parametr nomlari aynan TL sxemasidagidek. tg.client(...) dan farqi: xatolar Telethon shaklida emas, SDK shaklida keladi.

from telethon import functions

config = await tg.raw(functions.help.GetConfigRequest())

telethon.tl modulini qaytaradi: tg.tl().functions — so'rovlar, tg.tl().types — turlar (filtrlar, huquqlar). raw() va filter= parametrlari bilan birga ishlatiladi.

TelegramAccount.tl()

• ▸Statik metod — ulanishsiz ham chaqiriladi, lekin telethon o'rnatilgan bo'lishi kerak.