Клиент Instagram: методы Graph API

Обменивает code на краткосрочный токен в api.instagram.com (POST form-data), затем через ig_exchange_token — на долгосрочный и возвращает TokenBundle. Вызывается в callback Instagram Login.

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

• ▸По документации Meta краткосрочный токен действует 1 час, долгосрочный — 60 дней.
• ▸В redirect_uri передайте ровно то же значение, что было в ссылке входа.
• ▸Если краткосрочный токен не получен, будет ApiError.

Создаёт клиент в режиме Instagram Login из окружения: INSTAGRAM_APP_ID, INSTAGRAM_APP_SECRET и META_GRAPH_VERSION. Для работы через страницу используйте via_facebook.

Instagram.from_env(**kwargs) -> Instagram

• ▸Конструктор не проверяет пустые ключи: отсутствие app_id проявится как ConfigurationError при вызове login_url.

Формирует ссылку на диалог Instagram Login (https://www.instagram.com/oauth/authorize). Метод синхронный и запросов не отправляет.

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

• ▸Scope по умолчанию: instagram_business_basic, instagram_business_manage_messages, instagram_business_manage_comments, instagram_business_content_publish, instagram_business_manage_insights; сократите список через scopes=.
• ▸Без app_id будет ConfigurationError.
• ▸SDK не хранит state: сгенерируйте случайное значение и сравните его в callback.
• ▸По документации Meta code из callback действует 1 час и используется только один раз.

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

Обновляет долгосрочный токен пользователя Instagram через ig_refresh_token и возвращает новый TokenBundle. Запускайте регулярно по расписанию (cron), чтобы аккаунт не отвалился незаметно.

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

• ▸Правило Meta: токену должно быть не меньше 24 часов, и он не должен быть истёкшим; обновлённый токен действует 60 дней с даты обновления.
• ▸Только для токенов Instagram Login — при подключении через страницу используется токен страницы.
• ▸Если токен не вернулся, будет ApiError.

bundle = await ig.refresh_token(token)

Создаёт клиент для сценария Facebook Login: запросы идут на graph.facebook.com, в качестве токена ожидается токен страницы. app_id не нужен — OAuth проходит в клиенте Facebook, а секрет нужен для appsecret_proof.

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

• ▸В методах профиля, медиа, статистики и публикации ig_user_id обязателен (me здесь означает страницу); берите ID из Page.instagram_id.
• ▸В conversations и send_message обязателен также page_id.
• ▸login_url, exchange_code и refresh_token относятся к Instagram Login и в этом режиме не используются.

Возвращает список публикаций аккаунта в виде сырых словарей. limit — общее число публикаций; пагинацию SDK проходит сам.

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

• ▸Через страницу ig_user_id обязателен.
• ▸Для одной публикации используйте media_details.

Нужные разрешения:instagram_basic

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

Возвращает данные одной публикации по media_id. publish возвращает только ID, поэтому permalink и остальные поля после публикации получайте этим методом.

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

Нужные разрешения:instagram_basic

post = await ig.media_details(media_id, page_token)

Возвращает профиль профессионального аккаунта в виде Profile: username, имя, фото, био, сайт, число подписчиков, подписок и публикаций. Нужен для отображения или синхронизации аккаунта после подключения.

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

• ▸Через страницу ig_user_id обязателен; в этом режиме SDK не запрашивает account_type, поэтому он будет None.
• ▸Полный ответ — в Profile.raw.

Нужные разрешения:instagram_basic

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

Публикует одно фото или видео: создаёт контейнер, для видео ждёт его готовности, затем вызывает media_publish. Возвращает {container_id, media_id}.

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 — публичная HTTPS-ссылка: Meta сама скачивает файл; изображения только в JPEG.
• ▸Видео всегда уходит как REELS — с 9 ноября 2023 года Meta не принимает media_type=VIDEO. is_reel выбирает только значение share_to_feed по умолчанию.
• ▸Если контейнер видео не готов за wait_timeout (по умолчанию 300 секунд) или получил статус ERROR, будет ContainerNotReadyError — передайте его container_id в publish_container().
• ▸Лимит Meta: до 100 публикаций через API за скользящие 24 часа на аккаунт (на части страниц Meta указывает 50) — точный остаток отдаёт content_publishing_limit.

Нужные разрешения: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 изображений одной каруселью: дочерний контейнер на каждое фото (параллельно), затем контейнер CAROUSEL, ожидание готовности и публикация. Возвращает {container_id, media_id, children}.

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, берутся первые 10; если меньше 2 — ConfigurationError.
• ▸Принимаются только ссылки на изображения — публичные HTTPS и в формате JPEG.
• ▸Если родительский контейнер не готов за wait_timeout (по умолчанию 300 секунд), будет ContainerNotReadyError — продолжите через publish_container().

Публикует ранее созданный контейнер: нужен, чтобы продолжить после ContainerNotReadyError из publish(), publish_carousel() или publish_story() без повторной загрузки файла.

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

• ▸container_id берите из исключения (ContainerNotReadyError.container_id); метод дожидается готовности контейнера и вызывает media_publish.
• ▸Контейнер живёт 24 часа: если за это время его не опубликовать, он получает статус EXPIRED и медиа придётся загружать заново.
• ▸Для длинного видео увеличьте wait_timeout — Meta рекомендует опрашивать статус раз в минуту и не дольше 5 минут.

Публикует фото или видео как историю (Stories). Поток тот же, что у publish() (контейнер → ожидание → media_publish), отличие одно: в контейнер добавляется media_type=STORIES. Возвращает {container_id, media_id}.

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 здесь нет намеренно: история — не пост в ленте, текст подписи в ней не показывается. Нужный текст должен быть вшит в само фото или видео.
• ▸Передаётся ровно один из image_url и video_url — публичная HTTPS-ссылка, как в publish() (файл скачивает сама Meta). Если переданы оба, будет ConfigurationError.
• ▸Требования Meta (SDK их не проверяет): фото — JPEG до 8 МБ, рекомендуемое соотношение 9:16; видео — MOV или MP4, 3–60 секунд, до 100 МБ, кодек H264 или HEVC, звук AAC 48 кГц.
• ▸Если контейнер видео не готов за wait_timeout (по умолчанию 300 секунд), будет ContainerNotReadyError; продолжить можно через publish_container() с его container_id.
• ▸История тоже публикуется через media_publish, то есть входит в суточный лимит публикаций. В самой документации Meta это число на разных страницах отличается — узнавайте остаток запросом GET /{ig-user-id}/content_publishing_limit.
• ▸Опубликованная история исчезает через 24 часа (архива и «актуального» в API нет). В эти 24 часа работают media_details() и media_insights(); что это история, показывает media_product_type == "STORY".
• ▸Разрешения: для Instagram Login — instagram_business_basic и instagram_business_content_publish; для Facebook Login — instagram_basic, instagram_content_publish и pages_read_engagement.

Нужные разрешения: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")

Возвращает истории аккаунта, активные прямо сейчас. Истории не попадают в edge media — для них у Meta отдельный edge stories, поэтому это отдельный метод.

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

• ▸Работает только в сценарии Facebook Login: в документации Meta этот edge помечен «Instagram API with Facebook Login only». В клиенте Instagram Login метод выбрасывает ConfigurationError, не отправляя запрос, — официального способа получить список активных историй там нет.
• ▸Видны только последние 24 часа: архива и «актуального» в API нет вовсе.
• ▸Каждая запись — объект IG Media; media_type и для истории равен IMAGE/VIDEO, а историю выдаёт media_product_type == "STORY" — SDK запрашивает это поле принудительно.
• ▸Ограничения Meta: истории прямых эфиров не возвращаются; новая история, созданная репостом чужой, в список не попадает; если у истории несколько подписей, вернётся одна.
• ▸Разрешения (Facebook Login): instagram_basic и pages_read_engagement.

Нужные разрешения:instagram_basicpages_read_engagement

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

Возвращает комментарии к публикации списком сырых словарей. limit — общее число комментариев, пагинация автоматическая.

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

• ▸Meta рекомендует вместо частого опроса использовать вебхуки комментариев — это защищает от rate limit.
• ▸Для Facebook Login Meta требует instagram_basic, instagram_manage_comments и pages_read_engagement, для Instagram Login — instagram_business_basic и instagram_business_manage_comments.

Нужные разрешения:instagram_manage_comments

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

Удаляет комментарий через DELETE /{comment_id}. Действие необратимо — часто достаточно hide_comment.

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

Нужные разрешения:instagram_manage_comments

await ig.delete_comment(comment_id, page_token)

Скрывает комментарий (hide=true) или снова показывает его при hidden=False. Обратимая альтернатива удалению.

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

Нужные разрешения:instagram_manage_comments

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

Отвечает на комментарий от имени аккаунта (POST /{comment_id}/replies) и возвращает id нового комментария.

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

Нужные разрешения:instagram_manage_comments

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

Возвращает профиль собеседника (User Profile API) по IGSID. При ошибке исключение не выбрасывается: возвращается {id, available: False, reason}, при успехе добавляется available: True.

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

• ▸Правило Meta: профиль доступен только после согласия пользователя — если он написал бизнесу, нажал icebreaker или пункт постоянного меню. Профиль человека, который только оставил комментарий, получить нельзя.
• ▸По документации Meta ссылка profile_pic истекает через несколько дней — не кешируйте её надолго.

Нужные разрешения:instagram_manage_messages

contact = await ig.contact(igsid, page_token)

Возвращает список диалогов Direct в виде {data, paging}: в каждом contact (клиент), contacts, last_message, updated_time. При enrich=True профиль каждого собеседника параллельно запрашивается через User Profile API.

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

• ▸Возвращается одна страница: для следующей передайте курсор из paging в after=.
• ▸Через страницу page_id обязателен, к запросу добавляется platform=instagram; в Instagram Login вызывается /me/conversations.
• ▸ig_user_id и page_id нужны, чтобы отделить бизнес от клиента, — передавайте их, иначе в contact может попасть сам бизнес.
• ▸Ограничение Meta: доступны детали только 20 последних сообщений диалога; диалоги из папки «Запросы», неактивные 30 дней, не возвращаются.

Нужные разрешения: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"])

Читает сообщения одного диалога из edge messages и возвращает ответ Graph API (data, paging). Для следующей страницы передайте курсор after.

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

• ▸Ограничение Meta: детали доступны только для 20 последних сообщений; на более старое вернётся ошибка, что сообщение удалено.

Нужные разрешения:instagram_manage_messages

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

Отправляет текстовое сообщение в Direct (POST /{id}/messages, recipient.id — IGSID). Нужен для ответа клиенту, пришедшему из вебхука или conversations.

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

• ▸Окно 24 часа: Meta разрешает ответить в течение 24 часов после сообщения клиента, потом отклоняет запрос (в SDK — PermissionError).
• ▸Требование Meta: текст в UTF-8 и не длиннее 1000 байт.
• ▸Через страницу page_id обязателен; в Instagram Login используется ig_user_id или me.
• ▸Только текст: изображений, шаблонов и тегов сообщений в этом методе нет.

Нужные разрешения:instagram_manage_messages

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

Подписывает аккаунт на вебхуки приложения в сценарии Instagram Login (subscribed_apps) и возвращает bool. Даже при настроенном в App Dashboard вебхуке события комментариев и Direct не приходят, пока аккаунт не подписан.

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

• ▸Вызывайте сразу после exchange_code() — иначе первые события будут потеряны.
• ▸Без fields отправляется список по умолчанию: comments, messages, messaging_postbacks, message_reactions.
• ▸Для аккаунта, подключённого через страницу, метод не используется: там подписка оформляется на странице (Facebook.subscribe_page), и события IG приходят через неё. В этом режиме метод выбрасывает ConfigurationError.

Возвращает демографию подписчиков в разрезах age,gender, city и country (follower_demographics, timeframe=this_month). Каждый разрез — отдельный запрос: если один не сработал, остальные всё равно вернутся.

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

• ▸Результат: {разрез: {available, values}}; values — плоский словарь с ключами вида 25-34 / F, при ошибке — available: False и reason.
• ▸Правило Meta: для аккаунтов с менее чем 100 подписчиками демография не возвращается.

Нужные разрешения:instagram_manage_insights

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

Возвращает суммарные метрики аккаунта за период в виде {since, until, metrics}. SDK запрашивает reach, profile_views, website_clicks, accounts_engaged и total_interactions с period=day и metric_type=total_value.

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

• ▸Период ограничивается в SDK: until в будущем сдвигается на сегодня, без since берутся последние 30 дней, период длиннее 30 дней обрезается.
• ▸Meta убрала profile_views и website_clicks из метрик аккаунта для всех версий с 8 января 2025 года. Если Graph API отклонит такой запрос, будет ApiError.
• ▸По документации Meta данные могут запаздывать до 48 часов.

Нужные разрешения:instagram_manage_insights

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

Возвращает статистику одной публикации как {метрика: значение}. Набор зависит от типа: reach, likes, comments, saved, shares, total_interactions; для фото добавляется profile_visits, для видео и Reels — views, для Stories — reach, replies, navigation, total_interactions.

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

• ▸При ошибке API исключение не выбрасывается — возвращается {}.
• ▸Правила Meta: метрики Stories доступны только 24 часа; для отдельных элементов внутри альбома (карусели) статистики нет.

Нужные разрешения:instagram_manage_insights

stats = await ig.media_insights(media_id, page_token)

Отправляет произвольный HTTP-запрос и возвращает JSON-ответ — для эндпоинта, у которого в SDK пока нет отдельного метода. Токен и параметры подписи (access_token, для Meta — appsecret_proof через socialift.crypto.appsecret_proof) вы передаёте сами в params или headers.

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

• ▸Значения None в params не отправляются.
• ▸При лимите (RateLimitError) и временных ошибках сервера (HTTP 429, 500, 502, 503, 504) запрос повторяется по RetryPolicy; если есть заголовок Retry-After, SDK ждёт указанное время. Обрыв сети выбрасывается как TransportError.

Короткая форма request("GET", ...).

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

Короткая форма request("POST", ...).

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

Короткая форма request("DELETE", ...).

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

Проходит по курсорной пагинации Meta (paging.next) и возвращает все элементы data одним списком.

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

• ▸max_items (по умолчанию 500) — защитный предел: у крупного аккаунта могут быть десятки тысяч записей. page_size — limit одного запроса.

Закрывает HTTP-сессию, созданную самим SDK (переданную извне сессию не трогает). При использовании async with Client(...) вызывается автоматически.

await ig.close() -> None