Быстрый старт с Socialift SDK

Коротко: как начать работу с Socialift SDK?

Что понадобится для старта?

Шаг 1: установить SDK и настроить ключ

1. 1

   Установите пакет

   pip install socialift. Базовые зависимости — только aiohttp и cryptography. Если нужен живой аккаунт Telegram (TelegramAccount, MTProto): pip install 'socialift[telegram]' — добавится Telethon; для Telegram-бота это не требуется.

2. 2

   Получите лицензионный ключ

   socialift.uz/dashboard → «Tokenlar» (токены) → «Yangi token» (новый токен). Ключ начинается с slk_; скопируйте его кнопками «Kalitni ko'rsatish» (показать ключ) и «Nusxa» (копировать). Первый месяц бесплатно, и в это время открыты все возможности SDK.

3. 3

   Запишите ключ в переменную окружения

   SOCIALIFT_LICENSE_KEY=slk_.... Не храните ключ в коде — клиенты сами читают его из окружения. Ключ проверяется не при импорте, а перед первым запросом.

4. 4

   В контейнере задайте имя окружения

   В Docker или Kubernetes задайте стабильное значение вроде SOCIALIFT_INSTANCE_ID=my-app-prod — иначе каждый деплой займёт новый seat. Подробно — на странице «Аутентификация».

В терминале: установка и ключ

python -m pip install socialift
python -m pip install "socialift[telegram]"   # только для TelegramAccount (MTProto)

export SOCIALIFT_LICENSE_KEY="slk_..."
# Windows PowerShell: $env:SOCIALIFT_LICENSE_KEY="slk_..."

python -c 'import socialift; print(socialift.__version__)'

Путь A: Telegram-бот — первое сообщение за пару минут

Создайте бота командой /newbot в @BotFather, запишите токен в TELEGRAM_BOT_TOKEN и напишите боту любое сообщение в Telegram — скрипт возьмёт chat ID из этого сообщения.

import asyncio
from socialift import Telegram


async def main():
    async with Telegram.from_env() as bot:        # читает TELEGRAM_BOT_TOKEN
        me = await bot.get_me()
        print("Бот:", me["username"])

        updates = await bot.get_updates(timeout=0)
        messages = [u["message"] for u in updates if "message" in u]
        if not messages:
            print("Сначала напишите боту в Telegram")
            return
        chat_id = messages[-1]["chat"]["id"]
        await bot.send_message(chat_id, "Привет! Socialift SDK работает.")


asyncio.run(main())

Путь B: Facebook и Instagram через OAuth

Если аккаунт Instagram Business или Creator привязан к странице Facebook, токен получают через Facebook Login, а запросы к Instagram идут с токеном страницы.

1. 1

   Создайте Meta-приложение

   Создайте приложение на developers.facebook.com и запишите App ID и App Secret в FACEBOOK_APP_ID и FACEBOOK_APP_SECRET. Подробно — в руководстве «Настройка Meta-приложения».

2. 2

   Зарегистрируйте Redirect URI

   Добавьте адрес callback в настройки Facebook Login (например, https://example.uz/auth/facebook/callback). В login_url() и exchange_code() нужно передать ровно этот адрес, символ в символ.

3. 3

   Запросите разрешения

   Чтобы прочитать страницы и привязанный Instagram, нужны pages_show_list и instagram_basic. При конфигурации Facebook Login for Business вместо scopes передаётся config_id.

4. 4

   Отправьте пользователя на вход

   fb.login_url(...) возвращает ссылку. Сохраните state в сессии и сравните в callback — SDK его не хранит.

5. 5

   В callback получите токен и страницы

   exchange_code() меняет код на долгоживущий токен пользователя, а pages() возвращает страницы с токеном страницы и ID привязанного Instagram.

Ссылка для входа

import secrets
from socialift import Facebook

REDIRECT_URI = "https://example.uz/auth/facebook/callback"

fb = Facebook.from_env()              # FACEBOOK_APP_ID, FACEBOOK_APP_SECRET
state = secrets.token_urlsafe(32)     # сохраните в сессии
url = fb.login_url(
    redirect_uri=REDIRECT_URI,
    state=state,
    scopes=["pages_show_list", "instagram_basic"],
)
print(url)

Callback: токен, страницы и профиль Instagram

import asyncio
import os
from socialift import Facebook, Instagram

REDIRECT_URI = "https://example.uz/auth/facebook/callback"


async def handle_callback(code: str):
    async with Facebook.from_env() as fb:
        user = await fb.exchange_code(code, redirect_uri=REDIRECT_URI)
        pages = await fb.pages(user.access_token)

    async with Instagram.via_facebook(app_secret=os.environ["FACEBOOK_APP_SECRET"]) as ig:
        for page in pages:
            if not page.instagram_id:
                continue
            profile = await ig.profile(page.access_token, ig_user_id=page.instagram_id)
            posts = await ig.media(page.access_token, ig_user_id=page.instagram_id, limit=5)
            print(page.name, "->", profile.username, len(posts), "постов")


asyncio.run(handle_callback(code="параметр code из callback URL"))

Проверить без кода: Playground

Что дальше: перед выходом в продакшен

• ▸В контейнерах задайте стабильный SOCIALIFT_INSTANCE_ID — страница «Аутентификация».
• ▸Обрабатывайте AuthError, PermissionError и RateLimitError по отдельности — страница «Ошибки».
• ▸Проверяйте подпись вебхука по сырому телу — страница «Вебхуки».
• ▸Следите за сроком токенов: TokenBundle.expires_at и is_expiring().
• ▸Все методы и параметры — в разделах SDK reference.