Facebook klienti: Graph API metodlari

Callback'ga kelgan code ni qisqa muddatli, so'ng darhol uzoq muddatli foydalanuvchi tokeniga almashtiradi va TokenBundle qaytaradi. OAuth callback'ida bir marta chaqiriladi.

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

• ▸redirect_uri login havolasidagi qiymat bilan aynan bir xil bo'lishi shart (Meta talabi).
• ▸Meta hujjatiga ko'ra uzoq muddatli foydalanuvchi tokeni odatda taxminan 60 kun amal qiladi; muddatni TokenBundle.expires_at dan oling va tokenni o'zingiz saqlang.
• ▸Meta token qaytarmasa ApiError ko'tariladi.

Klientni muhit o'zgaruvchilaridan yaratadi: FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, FACEBOOK_CONFIG_ID va META_GRAPH_VERSION. Kalitlar kodda turmasligi kerak bo'lgan server ilovalari uchun.

Facebook.from_env(**kwargs) -> Facebook

• ▸FACEBOOK_APP_ID yoki FACEBOOK_APP_SECRET bo'sh bo'lsa ConfigurationError ko'tariladi.
• ▸Qo'shimcha argumentlar (timeout, retry, session, license_key) konstruktorga uzatiladi.

Token'ga haqiqatda berilgan ruxsatlar ro'yxatini debug_token orqali qaytaradi. Foydalanuvchi dialogda ba'zi ruxsatlarni rad etishi mumkin, shuning uchun funksiyalarni so'ralgan emas, shu ro'yxatga qarab yoqing.

await fb.granted_scopes(token: str) -> list[str]

• ▸So'rov app tokeni (app_id|app_secret) bilan yuboriladi; argumentga tekshirilayotgan tokenni bering.
• ▸Ruxsatlar topilmasa bo'sh ro'yxat qaytadi.

Foydalanuvchini Facebook Login dialogiga yuborish uchun havola yasaydi; metod sinxron va so'rov yubormaydi. config_id (argumentda yoki klientda) bo'lsa Facebook Login for Business oqimi, aks holda scopes ro'yxati ishlatiladi.

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

• ▸SDK state ni saqlamaydi: tasodifiy qiymat yarating (masalan secrets.token_urlsafe(32)), sessiyada saqlang va callback'da solishtiring — Meta uni CSRF'dan himoya deb belgilaydi.
• ▸config_id bo'lsa scope umuman yuborilmaydi: ruxsatlar App Dashboard'dagi konfiguratsiyadan olinadi. Login for Business faqat Business turidagi app'da ishlaydi.

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

App'ning barcha ruxsatlarini Facebook tomonida bekor qiladi (DELETE /{user_id}/permissions) va bool qaytaradi. Foydalanuvchi integratsiyani uzganda chaqiring — tokenni faqat bazadan o'chirish yetarli emas.

await fb.revoke(token: str, *, user_id: str = 'me') -> bool

• ▸Meta hujjatiga ko'ra barcha ruxsatlar bekor qilinsa foydalanuvchining access tokenlari yaroqsiz bo'ladi va u qaytadan login qilishi kerak.
• ▸Foydalanuvchi tokeni bilan chaqiriladi; user_id standart holda me.

await fb.revoke(user_token)

Token egasining Facebook profilini Profile ko'rinishida qaytaradi: id, ism, rasm va email. Login'dan keyin kim ulanganini aniqlash uchun.

await fb.me(token: str) -> socialift.models.Profile

• ▸Foydalanuvchi tokeni kerak (page token emas).
• ▸email bo'sh bo'lishi mumkin; to'liq javob Profile.raw da.

Foydalanuvchi boshqaradigan Page'larni Page obyektlari sifatida qaytaradi: har biri page token (access_token) va bog'langan Instagram professional akkaunti (instagram_id, instagram_username) bilan. Post, izoh, webhook va lead metodlari uchun token shu yerdan olinadi.

await fb.pages(token: str) -> list[socialift.models.Page]

• ▸Foydalanuvchi tokeni bilan chaqiriladi.
• ▸Meta hujjatiga ko'ra uzoq muddatli foydalanuvchi tokeni bilan olingan page tokenning amal qilish muddati yo'q va u faqat muayyan holatlarda bekor bo'ladi.
• ▸Page.access_token maxfiy: frontendga bermang va log'ga yozmang (repr da ko'rinmaydi).
• ▸Sahifalash avtomatik, ko'pi bilan 500 ta Page.

Kerakli ruxsatlar:pages_show_list

for page in await fb.pages(user_token):
    print(page.name, page.instagram_username)

Page'ni app webhook'iga obuna qiladi (POST /{page_id}/subscribed_apps). App darajasida webhook sozlangan bo'lsa ham, Page obuna qilinmaguncha undan hodisa kelmaydi.

await fb.subscribe_page(
    page_id: str,
    page_token: str,
    fields: Optional[list[str]] = None,
) -> bool

• ▸Page token kerak; Meta pages_manage_metadata va pages_show_list ruxsatlarini talab qiladi.
• ▸fields berilmasa standart ro'yxat yuboriladi: leadgen, leadgen_update, feed, messages, messaging_postbacks, mention. Meta messages maydoni uchun pages_messaging ruxsatini ham talab qiladi — u bo'lmasa fields ni aniq bering.
• ▸Meta qoidasi: Instagram webhook'lari subscribed_fields orqali sozlanmaydi.

Kerakli ruxsatlar:pages_manage_metadata

await fb.subscribe_page(page_id, page_token, fields=["leadgen", "feed"])

Page qaysi app'larga va qaysi maydonlar bo'yicha obuna bo'lganini qaytaradi. Webhook hodisalari kelmay qolganda diagnostika uchun.

await fb.subscriptions(page_id: str, page_token: str) -> list[dict]

• ▸Page token bilan chaqiriladi; Graph API javobidagi data ro'yxati o'zgarishsiz qaytadi.

apps = await fb.subscriptions(page_id, page_token)

App'ning Page'dagi webhook obunasini o'chiradi (DELETE /{page_id}/subscribed_apps) va bool qaytaradi. Mijoz Page'ni uzganda chaqiring.

await fb.unsubscribe_page(page_id: str, page_token: str) -> bool

• ▸Obuna o'chgach shu Page'dan lead, izoh va boshqa hodisalar kelmaydi.

await fb.unsubscribe_page(page_id, page_token)

Page postini butunlay o'chiradi (DELETE /{post_id}) va bool qaytaradi. Qaytarib bo'lmaydi.

await fb.delete_post(post_id: str, page_token: str) -> bool

• ▸Page token kerak; post_id — posts() yoki publish_post() qaytargan id.

Kerakli ruxsatlar:pages_manage_posts

await fb.delete_post(post_id, page_token)

Post statistikasini {metrika: qiymat} lug'ati sifatida qaytaradi. SDK post_impressions, post_impressions_unique, post_engaged_users, post_clicks va post_reactions_by_type_total metrikalarini so'raydi.

await fb.post_insights(post_id: str, page_token: str) -> dict[str, Any]

• ▸API xatosida istisno ko'tarilmaydi — bo'sh lug'at {} qaytadi (masalan, eski postda statistika bo'lmasa).
• ▸Meta post_impressions ni 2025-yil 15-noyabrdan barcha API versiyalarida bekor qilgan, post_impressions_unique ham bekor qilinganlar ro'yxatida (o'rniga post_media_view, post_total_media_view_unique). Bekor qilingan metrika uchun Graph API xato beradi, shuning uchun metod {} qaytarishi mumkin.
• ▸Page token kerak; Meta read_insights va pages_read_engagement ni talab qiladi.

Kerakli ruxsatlar:read_insightspages_read_engagement

stats = await fb.post_insights(post_id, page_token)

Page'ning e'lon qilingan postlarini /published_posts orqali o'qiydi. /feed ishlatilmaydi, chunki unga Page'dagi boshqa odamlarning yozuvlari ham tushadi.

await fb.posts(page_id: str, page_token: str, *, limit: int = 25) -> list[dict]

• ▸Page token bilan chaqiriladi.
• ▸limit — jami nechta post qaytishi; sahifalarni SDK o'zi yuradi.
• ▸Meta hujjatiga ko'ra endpoint bir yil uchun taxminan 600 ta postni qaytaradi.

Kerakli ruxsatlar:pages_read_engagement

posts = await fb.posts(page_id, page_token, limit=25)

Page nomidan matnli post (ixtiyoriy havola bilan) /{page_id}/feed ga joylaydi va post id si bor Meta javobini qaytaradi. published=False Meta'ga published=false yuboradi — post darhol e'lon qilinmaydi.

await fb.publish_post(
    page_id: str,
    page_token: str,
    *,
    message: str,
    link: Optional[str] = None,
    published: bool = True,
) -> dict

• ▸Page token kerak. Meta'ning Pages API qo'llanmasida pages_manage_posts, pages_manage_engagement, pages_read_engagement ruxsatlari va Page'da CREATE_CONTENT, MANAGE, MODERATE vazifalari ko'rsatilgan.
• ▸Faqat matn va havola: bu metodda rasm yoki video yuklash yo'q.
• ▸scheduled_publish_time yuborilmaydi, ya'ni bu rejalashtirish emas.

Kerakli ruxsatlar:pages_manage_postspages_read_engagement

post = await fb.publish_post(page_id, page_token, message="Salom!", link="https://siz.uz")

Rasmni Page story qilib e'lon qiladi va {photo_id, post_id, success} qaytaradi. Ikki qadam: rasm avval POST /{page-id}/photos ga published=false bilan yuklanadi, so'ng olingan photo_id photo_stories edge'iga beriladi.

await fb.publish_photo_story(
    page_id: str,
    page_token: str,
    *,
    photo_url: Optional[str] = None,
    photo_id: Optional[str] = None,
) -> dict

• ▸Meta photo_stories ga faqat photo_id qabul qiladi, havola qabul qilmaydi — shuning uchun birinchi qadamni o'tkazib bo'lmaydi; SDK uni o'zi bajaradi.
• ▸photo_url (ochiq havola, faylni Meta o'zi yuklab oladi) yoki photo_id (allaqachon yuklangan, e'lon qilinmagan rasm) dan aniq bittasi beriladi. Ikkinchi qadam uzilib qolsa, photo_id bilan rasmni qaytadan yuklamasdan davom etish mumkin.
• ▸Meta talablari: .jpeg, .bmp, .png, .gif yoki .tiff, 10 MB gacha (.png uchun 1 MB tavsiya etiladi). Oldingi postdagi media qayta ishlatilmaydi — har story uchun yangi yuklash kerak.
• ▸E'lon qilinmagan rasm Facebook serverida taxminan 24 soat turadi: photo_id shu muddat ichida yaroqli.
• ▸Ruxsatlar: pages_manage_posts, pages_read_engagement, pages_show_list va Page'da CREATE_CONTENT vazifasi. Page token bilan chaqiriladi.

Kerakli ruxsatlar:pages_manage_postspages_read_engagementpages_show_list

story = await fb.publish_photo_story(page_id, page_token,
                                        photo_url="https://cdn.siz.uz/story.jpg")

Videoni Page story qilib e'lon qiladi va {video_id, post_id, success} qaytaradi. Meta bu yerda uch bosqichli «resumable upload» talab qiladi: upload_phase=start → javobdagi upload_url ga fayl yuklash → upload_phase=finish.

await fb.publish_video_story(
    page_id: str,
    page_token: str,
    *,
    video_url: Optional[str] = None,
    video: Union[bytes, bytearray, str, os.PathLike, NoneType] = None,
    wait_timeout: float = 300.0,
    upload_attempts: int = 3,
) -> dict

• ▸video_url (ochiq havola — Meta faylni o'zi yuklab oladi) yoki video (baytlar yoki lokal fayl yo'li) dan aniq bittasi beriladi.
• ▸upload_url javobdan olinadi va o'zgartirilmaydi (u rupload.facebook.com ga ishora qiladi); ikkinchi qadamda token query'da emas, Authorization: OAuth sarlavhasida ketadi.
• ▸Yuklash uzilsa Meta nechta bayt yetib borganini aytadi va SDK o'sha joydan davom ettiradi — upload_attempts (standart 3) gacha urinadi, faylni boshidan qayta yubormaydi.
• ▸Uchinchi qadamdan oldin yuklash holati complete bo'lguncha wait_timeout (standart 300 soniya) kutiladi. Vaqt tugasa ApiError ko'tariladi va uning payload ida video_id qoladi — holatni video_story_status() bilan tekshirish mumkin.
• ▸Meta talablari (SDK tekshira olmaydi): .mp4, kodek H.264 yoki H.265, ovoz AAC 48 kHz; nisbat 9:16, o'lcham 540x960 dan 1080x1920 gacha, 24–60 FPS. Davomiylik uchun Meta hujjatida ikki xil chegara uchraydi (3–90 s va «60 soniyadan oshmasin») — xavfsizi 3–60 soniya.
• ▸Past sifatli fayl xatosi (masalan «Resolution too low») uchinchi qadamda emas, yuklashdan keyingi holatda chiqadi; matn to'liq ApiError.payload da saqlanadi.

Kerakli ruxsatlar:pages_manage_postspages_read_engagementpages_show_list

story = await fb.publish_video_story(page_id, page_token,
                                        video_url="https://cdn.siz.uz/story.mp4")

Page'ning story'larini qaytaradi: har yozuvda post_id, status, creation_time, media_type, media_id va url. Joylangan story'ni keyin kuzatish uchun publish_photo_story()/publish_video_story() qaytargan post_id shu ro'yxatdagi yozuv bilan bog'lanadi.

await fb.stories(page_id: str, page_token: str, *, limit: int = 25) -> list[dict]

• ▸SDK ataylab fields yubormaydi: Meta bu edge uchun maydon tanlashni hujjatlashtirmagan, noma'lum fields esa Graph API'da butun so'rovni yiqitadi.
• ▸Arxivlangan story'lar faqat Page'da arxiv yoqilgan bo'lsa qaytariladi.
• ▸Ruxsatlar: pages_read_engagement va pages_show_list; Page token bilan chaqiriladi.

Kerakli ruxsatlar:pages_read_engagementpages_show_list

stories = await fb.stories(page_id, page_token, limit=25)

Video story'ning yuklash va qayta ishlash holatini qaytaradi (GET /{video-id}?fields=status): uploading_phase, processing_phase va publishing_phase, har birida status — not_started, in_progress, complete yoki error.

await fb.video_story_status(video_id: str, page_token: str) -> dict

• ▸Yuklash bosqichida qo'shimcha bytes_transfered maydoni bo'ladi (Meta hujjatidagi imlo shunday) — uzilgan yuklashni qayerdan davom ettirishni shu ko'rsatadi.
• ▸publish_video_story() ApiError bilan tugasa, video_id istisnoning payload ida qoladi: nima bo'lganini aynan shu metod bilan bilib olasiz.
• ▸Page token bilan chaqiriladi.

Post izohlarini eng yangisidan boshlab (order=reverse_chronological) qaytaradi. Moderatsiya navbatini to'ldirish yoki izohlarni CRM'ga olib kelish uchun.

await fb.comments(post_id: str, page_token: str, *, limit: int = 50) -> list[dict]

• ▸Page token kerak. Meta hujjatiga ko'ra Page postidagi izoh ID'larini olish uchun shu Page'da moderator huquqi bo'lishi shart.
• ▸filter yuborilmaydi, shuning uchun Graph API standarti ishlaydi: faqat yuqori darajadagi izohlar, javoblar kirmaydi.
• ▸limit — jami izohlar soni; sahifalash avtomatik.

Kerakli ruxsatlar:pages_read_engagement

comments = await fb.comments(post_id, page_token, limit=50)

Izohni yashiradi (is_hidden=true) yoki hidden=False bilan qayta ochadi. O'chirishning qaytariladigan muqobili.

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

• ▸Meta hujjatiga ko'ra is_hidden faqat Page izohlariga tegishli.
• ▸Page token bilan chaqiriladi.

Kerakli ruxsatlar:pages_manage_engagement

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

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

await fb.reply_comment(comment_id: str, page_token: str, message: str) -> dict

• ▸Meta hujjatiga ko'ra izoh yozish uchun Page'da MODERATE vazifasini bajara oladigan foydalanuvchining page tokeni va pages_manage_engagement ruxsati kerak.

Kerakli ruxsatlar:pages_manage_engagement

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

Lead kelgan reklama kontekstini qaytaradi: reklama, ad set va kampaniya ID/nomlari, objective, optimization_goal va targeting. CRM'da lead manbasini ko'rsatish uchun.

await fb.ad_context(ad_id: Optional[str], token: str) -> dict

• ▸Istisno ko'tarmaydi: API xatosida (masalan ads_management ruxsati bo'lmasa) yoki ad_id bo'sh bo'lsa {} qaytadi.
• ▸Kalitlar: ad_id, ad_name, adset_id, adset_name, campaign_id, campaign_name, objective, optimization_goal, targeting.

Kerakli ruxsatlar:ads_management

context = await fb.ad_context(ad_id, token)

Webhook leadgen hodisasidagi leadgen_id bo'yicha bitta to'liq lead'ni Lead sifatida qaytaradi. Lead'ni real vaqtda CRM'ga yozishning asosiy yo'li.

await fb.lead(leadgen_id: str, page_token: str) -> socialift.models.Lead

• ▸Meta webhook'ida faqat identifikatorlar keladi (leadgen_id, page_id, form_id, adgroup_id, ad_id, created_time) — forma javoblari shu metod bilan olinadi.
• ▸Page token va leads_retrieval ruxsati kerak.

Page'dagi Lead Ads formalarini LeadForm ro'yxati sifatida qaytaradi: nom, holat, til, savollar va lead'lar soni. Formani tanlash va savollarni CRM maydonlariga moslashtirish uchun.

await fb.lead_forms(page_id: str, page_token: str) -> list[socialift.models.LeadForm]

• ▸Page token kerak; sahifalash avtomatik, xom javob LeadForm.raw da.

Kerakli ruxsatlar:leads_retrievalpages_manage_ads

forms = await fb.lead_forms(page_id, page_token)

Bitta formaga kelgan lead'larni Lead ro'yxati sifatida qaytaradi. since (unix timestamp) bilan faqat keyingi lead'larni olib, webhook o'tkazib yuborgan davrni to'ldirish (backfill) mumkin.

await fb.leads(
    form_id: str,
    page_token: str,
    *,
    since: Optional[int] = None,
    limit: int = 200,
) -> list[socialift.models.Lead]

• ▸since Graph API'ga time_created bo'yicha GREATER_THAN filtri bo'lib yuboriladi.
• ▸Lead.fields — normallashtirilgan maydonlar (full_name, email, phone va h.k.), Lead.field_data — Meta'dan kelgan xom ro'yxat.
• ▸Meta hujjatiga ko'ra lead'larni o'qish uchun leads_retrieval, ads_management, pages_show_list, pages_read_engagement, pages_manage_ads ruxsatlari va reklama kabinetida reklama bera oladigan odamning tokeni kerak.
• ▸limit standart 200; sahifalash avtomatik.

Kerakli ruxsatlar:leads_retrieval

leads = await fb.leads(form_id, page_token, limit=200)
for lead in leads:
    print(lead.fields.get("phone"), lead.campaign_name)

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 fb.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 fb.get(url: str, **kw) -> Any

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

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

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

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

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

await fb.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 fb.close() -> None