Instagram klienti: Graph API metodlari

code ni api.instagram.com da (POST form-data) qisqa muddatli tokenga, so'ng ig_exchange_token bilan uzoq muddatli tokenga almashtiradi va TokenBundle qaytaradi. Instagram Login callback'ida chaqiriladi.

await ig.exchange_code(code: str, *, redirect_uri: str) -> socialift.models.TokenBundle

• ▸Meta hujjatiga ko'ra qisqa muddatli token 1 soat, uzoq muddatli token 60 kun amal qiladi.
• ▸redirect_uri ga login havolasidagi qiymatni aynan bering.
• ▸Qisqa muddatli token kelmasa ApiError ko'tariladi.

Instagram Login rejimidagi klientni muhitdan yaratadi: INSTAGRAM_APP_ID, INSTAGRAM_APP_SECRET va META_GRAPH_VERSION. Page orqali ishlash uchun via_facebook ishlatiladi.

Instagram.from_env(**kwargs) -> Instagram

• ▸Konstruktor bo'sh kalitlarda xato bermaydi: app_id yo'qligi login_url chaqirilganda ConfigurationError bo'lib chiqadi.

Instagram Login dialogiga (https://www.instagram.com/oauth/authorize) havola yasaydi. Metod sinxron, so'rov yubormaydi.

ig.login_url(
    *,
    redirect_uri: str,
    state: Optional[str] = None,
    scopes: Optional[list[str]] = None,
) -> str

• ▸Standart scope'lar: instagram_business_basic, instagram_business_manage_messages, instagram_business_manage_comments, instagram_business_content_publish, instagram_business_manage_insights; scopes= bilan kamaytiring.
• ▸app_id bo'lmasa ConfigurationError.
• ▸state ni SDK saqlamaydi: tasodifiy qiymat yarating va callback'da solishtiring.
• ▸Meta hujjatiga ko'ra callback'ga kelgan code 1 soat amal qiladi va faqat bir marta ishlatiladi.

url = ig.login_url(redirect_uri="https://siz.uz/cb", state=state)

Uzoq muddatli Instagram foydalanuvchi tokenini ig_refresh_token bilan yangilaydi va yangi TokenBundle qaytaradi. Akkaunt jimgina uzilib qolmasligi uchun rejalashtirilgan vazifa (cron) bilan muntazam chaqiring.

await ig.refresh_token(token: str) -> socialift.models.TokenBundle

• ▸Meta qoidasi: token kamida 24 soatlik va hali tugamagan bo'lishi kerak; yangilangan token yangilangan kundan boshlab 60 kun amal qiladi.
• ▸Faqat Instagram Login tokenlari uchun — Page orqali ulanishda page token ishlatiladi.
• ▸Javobda token bo'lmasa ApiError.

bundle = await ig.refresh_token(token)

Facebook Login oqimi uchun klient yaratadi: so'rovlar graph.facebook.com ga ketadi va token sifatida page token kutiladi. app_id kerak emas — OAuth Facebook klientida o'tadi, secret esa appsecret_proof uchun.

Instagram.via_facebook(*, app_secret: str, **kwargs) -> Instagram

• ▸Profil, media, statistika va nashr metodlarida ig_user_id majburiy (me bu yo'lda Page'ni bildiradi); ID'ni Page.instagram_id dan oling.
• ▸conversations va send_message da page_id ham majburiy.
• ▸login_url, exchange_code va refresh_token Instagram Login uchun — bu rejimda ishlatilmaydi.

Akkaunt postlari ro'yxatini xom lug'atlar sifatida qaytaradi. limit — jami nechta post olinadi, sahifalarni SDK o'zi yuradi.

await ig.media(
    token: str,
    *,
    ig_user_id: Optional[str] = None,
    limit: int = 25,
) -> list[dict]

• ▸Page orqali ig_user_id majburiy.
• ▸Bitta post kerak bo'lsa media_details ni ishlating.

Kerakli ruxsatlar:instagram_basic

posts = await ig.media(page_token, ig_user_id=ig_user_id, limit=25)

Bitta postning ma'lumotlarini media_id bo'yicha qaytaradi. publish faqat ID qaytargani uchun e'londan keyin permalink va boshqa maydonlarni shu metod bilan oling.

await ig.media_details(media_id: str, token: str) -> dict

Kerakli ruxsatlar:instagram_basic

post = await ig.media_details(media_id, page_token)

Professional akkaunt profilini Profile sifatida qaytaradi: username, ism, rasm, bio, veb-sayt, obunachilar, obunalar va postlar soni. Ulangandan keyin akkauntni ko'rsatish yoki sinxronlash uchun.

await ig.profile(
    token: str,
    *,
    ig_user_id: Optional[str] = None,
) -> socialift.models.Profile

• ▸Page orqali ig_user_id majburiy; bu rejimda SDK account_type ni so'ramaydi, shuning uchun u None bo'ladi.
• ▸To'liq javob Profile.raw da.

Kerakli ruxsatlar:instagram_basic

profile = await ig.profile(page_token, ig_user_id=ig_user_id)

Bitta rasm yoki videoni e'lon qiladi: konteyner yaratadi, video bo'lsa tayyor bo'lishini kutadi, keyin media_publish qiladi. {container_id, media_id} qaytaradi.

await ig.publish(
    token: str,
    *,
    ig_user_id: Optional[str] = None,
    caption: Optional[str] = None,
    image_url: Optional[str] = None,
    video_url: Optional[str] = None,
    is_reel: bool = False,
    share_to_feed: Optional[bool] = None,
    wait_timeout: float = 300.0,
) -> dict

• ▸image_url/video_url ochiq HTTPS havola bo'lishi kerak — Meta faylni o'zi yuklab oladi; rasm faqat JPEG.
• ▸Video har doim REELS sifatida ketadi — Meta 2023-yil 9-noyabrdan media_type=VIDEO ni qabul qilmaydi. is_reel faqat share_to_feed standartini tanlaydi.
• ▸Video konteyneri wait_timeout (standart 300 soniya) ichida tayyor bo'lmasa yoki holati ERROR bo'lsa ContainerNotReadyError ko'tariladi — undagi container_id ni publish_container() ga bering.
• ▸Meta limiti: akkaunt 24 soatlik siljuvchi oynada API orqali 100 tagacha post e'lon qila oladi (Meta'ning ayrim sahifalarida 50 deb yozilgan) — aniq qolgan kvotani content_publishing_limit beradi.

Kerakli ruxsatlar:instagram_content_publish

post = await ig.publish(page_token, ig_user_id=ig_user_id, caption="Yangi mahsulot",
                        image_url="https://cdn.siz.uz/photo.jpg")

2–10 ta rasmni bitta karusel post qilib e'lon qiladi: har rasmga bola-konteyner (parallel), so'ng CAROUSEL konteyner, tayyor bo'lishini kutish va e'lon. {container_id, media_id, children} qaytaradi.

await ig.publish_carousel(
    token: str,
    *,
    ig_user_id: Optional[str] = None,
    image_urls: Sequence[str],
    caption: Optional[str] = None,
    wait_timeout: float = 300.0,
) -> dict

• ▸10 tadan ortiq havola berilsa birinchi 10 tasi olinadi; 2 tadan kam bo'lsa ConfigurationError.
• ▸Faqat rasm havolalari qabul qilinadi — ochiq HTTPS va JPEG formatida.
• ▸Ota-konteyner wait_timeout (standart 300 soniya) ichida tayyor bo'lmasa ContainerNotReadyError ko'tariladi — publish_container() bilan davom ettiring.

Oldin yaratilgan konteynerni e'lon qiladi: publish(), publish_carousel() yoki publish_story() ContainerNotReadyError bergandan keyin faylni qayta yuklamasdan davom ettirish uchun.

await ig.publish_container(
    token: str,
    container_id: str,
    *,
    ig_user_id: Optional[str] = None,
    wait_timeout: float = 300.0,
) -> dict

• ▸container_id ni istisnodan oling (ContainerNotReadyError.container_id); metod konteyner tayyor bo'lguncha kutadi va media_publish qiladi.
• ▸Konteyner 24 soat yashaydi: shu vaqt ichida e'lon qilinmasa holati EXPIRED bo'ladi va mediani qaytadan yuklash kerak.
• ▸Uzun video uchun wait_timeout ni oshiring — Meta konteyner holatini daqiqasiga bir marta, 5 daqiqagacha so'rashni tavsiya qiladi.

Rasm yoki videoni story qilib e'lon qiladi. Oqim publish() bilan bir xil (konteyner → kutish → media_publish), farqi bitta: konteynerga media_type=STORIES qo'shiladi. {container_id, media_id} qaytaradi.

await ig.publish_story(
    token: str,
    *,
    ig_user_id: Optional[str] = None,
    image_url: Optional[str] = None,
    video_url: Optional[str] = None,
    wait_timeout: float = 300.0,
) -> dict

• ▸caption yo'q va bu ataylab: story lentadagi post emas, unda izoh matni ko'rinmaydi. Matn kerak bo'lsa u rasm yoki videoning o'ziga chizilgan bo'lishi kerak.
• ▸image_url yoki video_url dan aniq bittasi beriladi — publish() dagi kabi ochiq HTTPS havola (faylni Meta o'zi yuklab oladi). Ikkalasi birga berilsa ConfigurationError.
• ▸Meta talablari (SDK ularni tekshira olmaydi): rasm — JPEG, 8 MB gacha, tavsiya etilgan nisbat 9:16; video — MOV yoki MP4, 3–60 soniya, 100 MB gacha, kodek H264 yoki HEVC, ovoz AAC 48 kHz.
• ▸Video konteyneri wait_timeout (standart 300 soniya) ichida tayyor bo'lmasa ContainerNotReadyError ko'tariladi; container_id bilan publish_container() davom ettiradi.
• ▸Story ham media_publish orqali chiqadi, ya'ni kunlik e'lon chegarasiga kiradi. Meta hujjatining o'zida bu chegara sahifadan sahifaga farq qiladi — qolgan kvotani GET /{ig-user-id}/content_publishing_limit dan so'rab biling.
• ▸E'lon qilingan story 24 soatdan keyin yo'qoladi (arxiv va «highlights» API'da yo'q). Shu 24 soat ichida media_details() va media_insights() ishlaydi; story ekanini media_product_type == "STORY" bildiradi.
• ▸Ruxsatlar: Instagram Login'da instagram_business_basic + instagram_business_content_publish; Facebook Login'da instagram_basic + instagram_content_publish + pages_read_engagement.

Kerakli ruxsatlar:instagram_content_publishpages_read_engagement

story = await ig.publish_story(page_token, ig_user_id=ig_user_id,
                                image_url="https://cdn.siz.uz/story.jpg")

Akkauntning hozir faol story'larini qaytaradi. Story'lar media edge'iga tushmaydi — Meta ular uchun alohida stories edge'ini beradi, shuning uchun bu alohida metod.

await ig.stories(
    token: str,
    *,
    ig_user_id: Optional[str] = None,
    limit: int = 25,
) -> list[dict]

• ▸Faqat Facebook Login oqimida ishlaydi: Meta hujjatida bu edge «Instagram API with Facebook Login only» deb belgilangan. Instagram Login klientida metod so'rov yubormasdan ConfigurationError ko'taradi — Instagram Login'da faol story'lar ro'yxatini olishning rasmiy yo'li yo'q.
• ▸Faqat oxirgi 24 soat ko'rinadi: arxiv va «highlights» API'da umuman yo'q.
• ▸Har bir yozuv — IG Media obyekti; media_type story uchun ham IMAGE/VIDEO bo'ladi, story ekanini media_product_type == "STORY" bildiradi va SDK bu maydonni majburan so'raydi.
• ▸Meta cheklovlari: jonli efir story'lari qaytmaydi; foydalanuvchi story'ni qayta ulashganda hosil bo'lgan yangi story ham ro'yxatga kirmaydi; story'da bir nechta izoh bo'lsa ham bittasi qaytadi.
• ▸Ruxsatlar (Facebook Login): instagram_basic va pages_read_engagement.

Kerakli ruxsatlar:instagram_basicpages_read_engagement

stories = await ig.stories(page_token, ig_user_id=ig_user_id, limit=25)

Post izohlarini xom lug'atlar ro'yxati sifatida qaytaradi. limit — jami izohlar soni, sahifalash avtomatik.

await ig.comments(media_id: str, token: str, *, limit: int = 50) -> list[dict]

• ▸Meta tez-tez so'rash o'rniga izohlar webhook'idan foydalanishni tavsiya qiladi — bu rate limit'dan saqlaydi.
• ▸Facebook Login rejimida Meta instagram_basic, instagram_manage_comments va pages_read_engagement ni, Instagram Login'da instagram_business_basic va instagram_business_manage_comments ni talab qiladi.

Kerakli ruxsatlar:instagram_manage_comments

comments = await ig.comments(media_id, page_token, limit=50)

Izohni DELETE /{comment_id} bilan o'chiradi. Qaytarib bo'lmaydi — ko'p hollarda hide_comment yetarli.

await ig.delete_comment(comment_id: str, token: str) -> dict

Kerakli ruxsatlar:instagram_manage_comments

await ig.delete_comment(comment_id, page_token)

Izohni yashiradi (hide=true) yoki hidden=False bilan qayta ko'rsatadi. O'chirishning qaytariladigan muqobili.

await ig.hide_comment(comment_id: str, token: str, hidden: bool = True) -> dict

Kerakli ruxsatlar:instagram_manage_comments

await ig.hide_comment(comment_id, page_token, hidden=True)

Izohga akkaunt nomidan javob yozadi (POST /{comment_id}/replies) va yangi izoh id sini qaytaradi.

await ig.reply_comment(comment_id: str, token: str, message: str) -> dict

Kerakli ruxsatlar:instagram_manage_comments

await ig.reply_comment(comment_id, page_token, "Rahmat!")

Suhbatdoshning profilini (User Profile API) IGSID bo'yicha qaytaradi. Xato bo'lsa istisno ko'tarmaydi: {id, available: False, reason} qaytadi, muvaffaqiyatda available: True qo'shiladi.

await ig.contact(igsid: str, token: str) -> dict

• ▸Meta qoidasi: profil faqat foydalanuvchi rozilik bergandan keyin ochiladi — u biznesga yozgan, icebreaker yoki doimiy menyuni bosgan bo'lsa. Faqat izoh qoldirgan odamning profili olinmaydi.
• ▸Meta hujjatiga ko'ra profile_pic havolasi bir necha kunda eskiradi — uni uzoq keshlamang.

Kerakli ruxsatlar:instagram_manage_messages

contact = await ig.contact(igsid, page_token)

Direct suhbatlar ro'yxatini {data, paging} ko'rinishida qaytaradi: har suhbatda contact (mijoz), contacts, last_message, updated_time. enrich=True bo'lsa har bir suhbatdosh profili User Profile API'dan parallel olinadi.

await ig.conversations(
    token: str,
    *,
    ig_user_id: Optional[str] = None,
    page_id: Optional[str] = None,
    limit: int = 25,
    after: Optional[str] = None,
    enrich: bool = True,
) -> dict

• ▸Bitta sahifa qaytadi: keyingisi uchun paging dagi kursorni after= ga bering.
• ▸Page orqali page_id majburiy va so'rovga platform=instagram qo'shiladi; Instagram Login'da /me/conversations chaqiriladi.
• ▸ig_user_id va page_id biznesni mijozdan ajratish uchun ishlatiladi — ularni bering, aks holda contact ga biznesning o'zi tushishi mumkin.
• ▸Meta cheklovi: suhbatdagi faqat oxirgi 20 ta xabar tafsiloti olinadi; «Requests» papkasidagi 30 kundan beri faol bo'lmagan suhbatlar qaytmaydi.

Kerakli ruxsatlar:instagram_manage_messages

chats = await ig.conversations(page_token, page_id=page_id, ig_user_id=ig_user_id)
for chat in chats["data"]:
    print(chat["contact"]["name"])

Bitta suhbat xabarlarini messages edge'idan o'qiydi va Graph API javobini (data, paging) qaytaradi. Keyingi sahifa uchun after kursorini bering.

await ig.messages(
    conversation_id: str,
    token: str,
    *,
    limit: int = 50,
    after: Optional[str] = None,
) -> dict

• ▸Meta cheklovi: faqat oxirgi 20 ta xabar tafsilotini olish mumkin; eskiroq xabar so'ralsa u o'chirilgan degan xato keladi.

Kerakli ruxsatlar:instagram_manage_messages

history = await ig.messages(conversation_id, page_token, limit=50)

Direct'da matnli xabar yuboradi (POST /{id}/messages, recipient.id — IGSID). Webhook yoki conversations orqali kelgan mijozga javob berish uchun.

await ig.send_message(
    recipient_id: str,
    token: str,
    text: str,
    *,
    ig_user_id: Optional[str] = None,
    page_id: Optional[str] = None,
) -> dict

• ▸24 soatlik oyna: Meta mijoz xabaridan keyin 24 soat ichida javob berishga ruxsat beradi, keyin rad etadi (SDK'da PermissionError).
• ▸Meta talabi: matn UTF-8 va 1000 baytdan oshmasligi kerak.
• ▸Page orqali page_id majburiy; Instagram Login'da ig_user_id yoki me ishlatiladi.
• ▸Faqat matn: rasm, shablon va xabar teglari bu metodda yo'q.

Kerakli ruxsatlar:instagram_manage_messages

await ig.send_message(recipient_id, page_token, "Salom!", page_id=page_id)

Instagram Login oqimida akkauntni app webhook'iga obuna qiladi (subscribed_apps) va bool qaytaradi. App Dashboard'da webhook sozlangan bo'lsa ham, akkaunt obuna bo'lmaguncha izoh va Direct hodisalari kelmaydi.

await ig.subscribe_account(
    token: str,
    *,
    ig_user_id: Optional[str] = None,
    fields: Optional[Sequence[str]] = None,
) -> bool

• ▸exchange_code() dan keyin darhol chaqiring — aks holda birinchi hodisalar yo'qoladi.
• ▸fields berilmasa standart ro'yxat ketadi: comments, messages, messaging_postbacks, message_reactions.
• ▸Page orqali ulangan akkaunt uchun ishlatilmaydi: u yerda obuna Page'da bo'ladi (Facebook.subscribe_page) va IG hodisalari o'sha obuna orqali keladi. Bu rejimda metod ConfigurationError ko'taradi.

Obunachilar demografiyasini age,gender, city va country kesimlarida qaytaradi (follower_demographics, timeframe=this_month). Har kesim alohida so'rov: bittasi ishlamasa qolganlari baribir qaytadi.

await ig.demographics(token: str, *, ig_user_id: Optional[str] = None) -> dict

• ▸Natija: {kesim: {available, values}}; values — 25-34 / F kabi kalitli tekis lug'at, xatoda available: False va reason.
• ▸Meta qoidasi: obunachilari 100 tadan kam akkaunt uchun demografiya qaytarilmaydi.

Kerakli ruxsatlar:instagram_manage_insights

demo = await ig.demographics(page_token, ig_user_id=ig_user_id)

Akkauntning davr bo'yicha jami ko'rsatkichlarini {since, until, metrics} ko'rinishida qaytaradi. SDK reach, profile_views, website_clicks, accounts_engaged va total_interactions ni period=day, metric_type=total_value bilan so'raydi.

await ig.insights(
    token: str,
    *,
    ig_user_id: Optional[str] = None,
    since: Optional[datetime.date] = None,
    until: Optional[datetime.date] = None,
) -> dict[str, Any]

• ▸Oraliq SDK'da cheklanadi: kelajakdagi until bugunga tushiriladi, since berilmasa oxirgi 30 kun olinadi, 30 kundan uzun oraliq qisqartiriladi.
• ▸Meta profile_views va website_clicks ni 2025-yil 8-yanvardan barcha versiyalarda akkaunt insight'laridan olib tashlagan. Graph API bunday so'rovni rad etsa ApiError ko'tariladi.
• ▸Meta hujjatiga ko'ra ma'lumotlar 48 soatgacha kechikishi mumkin.

Kerakli ruxsatlar:instagram_manage_insights

stats = await ig.insights(page_token, ig_user_id=ig_user_id)

Bitta post statistikasini {metrika: qiymat} ko'rinishida qaytaradi. Metrikalar post turiga qarab tanlanadi: reach, likes, comments, saved, shares, total_interactions; rasmga profile_visits, video va Reels'ga views qo'shiladi, Story uchun reach, replies, navigation, total_interactions.

await ig.media_insights(media_id: str, token: str) -> dict[str, Any]

• ▸API xatosida istisno ko'tarilmaydi — {} qaytadi.
• ▸Meta qoidalari: Story metrikalari faqat 24 soat mavjud; albom (karusel) ichidagi alohida elementlar uchun statistika yo'q.

Kerakli ruxsatlar:instagram_manage_insights

stats = await ig.media_insights(media_id, page_token)

Istalgan HTTP so'rovni yuboradi va JSON javobni qaytaradi — SDK'da hali alohida metodi yo'q endpoint uchun. Token va imzo parametrlarini (access_token, Meta uchun appsecret_proof — socialift.crypto.appsecret_proof) o'zingiz params yoki headers ga qo'shasiz.

await ig.request(
    method: str,
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    data: Optional[Any] = None,
    json: Optional[Any] = None,
    headers: Optional[Mapping[str, str]] = None,
) -> Any

• ▸params dagi None qiymatlar yuborilmaydi.
• ▸Limit (RateLimitError) va vaqtinchalik server xatolarida (HTTP 429, 500, 502, 503, 504) RetryPolicy bo'yicha qayta uriniladi; Retry-After sarlavhasi bo'lsa, shuncha kutiladi. Tarmoq uzilishi TransportError bo'lib chiqadi.

request("GET", ...) ning qisqa shakli.

await ig.get(url: str, **kw) -> Any

request("POST", ...) ning qisqa shakli.

await ig.post(url: str, **kw) -> Any

request("DELETE", ...) ning qisqa shakli.

await ig.delete(url: str, **kw) -> Any

Meta'ning kursorli sahifalashi (paging.next) bo'yicha yurib, barcha data elementlarini bitta ro'yxatga yig'ib qaytaradi.

await ig.paginate(
    url: str,
    *,
    params: Optional[Mapping[str, Any]] = None,
    max_items: int = 500,
    page_size: int = 100,
) -> list[dict]

• ▸max_items (standart 500) — himoya chegarasi: yirik akkauntda ro'yxat o'n minglab yozuv bo'lishi mumkin. page_size — bitta so'rovdagi limit.

SDK o'zi yaratgan HTTP sessiyasini yopadi (tashqaridan berilgan sessiyaga tegmaydi). async with Client(...) ishlatilsa, o'zi chaqiriladi.

await ig.close() -> None