Get started with the Socialift SDK

In short: how do you get started with the Socialift SDK?

What do you need to start?

Step 1: install the SDK and configure the key

1. 1

   Install the package

   pip install socialift. The only core dependencies are aiohttp and cryptography. For a live Telegram user account (TelegramAccount, MTProto) run pip install 'socialift[telegram]', which adds Telethon; a Telegram bot does not need it.

2. 2

   Get a license key

   socialift.uz/dashboard → “Tokenlar” (Tokens) → “Yangi token” (New token). The key starts with slk_; copy it with “Kalitni ko'rsatish” (Show key) and “Nusxa” (Copy). The first month is free, with every SDK feature unlocked.

3. 3

   Put the key in an environment variable

   SOCIALIFT_LICENSE_KEY=slk_.... Keep it out of your code — clients read it from the environment. The key is checked before the first request, not at import time.

4. 4

   Name the environment in containers

   In Docker or Kubernetes set a stable value such as SOCIALIFT_INSTANCE_ID=my-app-prod; otherwise every deploy takes a new seat. Details are on the Authentication page.

In the terminal: install and set the key

python -m pip install socialift
python -m pip install "socialift[telegram]"   # only for TelegramAccount (MTProto)

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

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

Path A: a Telegram bot — first message in minutes

Create a bot with /newbot in @BotFather, put the token in TELEGRAM_BOT_TOKEN and send the bot any message in Telegram — the script picks the chat ID from that message.

import asyncio
from socialift import Telegram


async def main():
    async with Telegram.from_env() as bot:        # reads TELEGRAM_BOT_TOKEN
        me = await bot.get_me()
        print("Bot:", me["username"])

        updates = await bot.get_updates(timeout=0)
        messages = [u["message"] for u in updates if "message" in u]
        if not messages:
            print("Send your bot a message in Telegram first")
            return
        chat_id = messages[-1]["chat"]["id"]
        await bot.send_message(chat_id, "Hello! The Socialift SDK works.")


asyncio.run(main())

Path B: Facebook and Instagram via OAuth

When an Instagram Business or Creator account is linked to a Facebook Page, you get the token through Facebook Login and call Instagram with the Page token.

1. 1

   Create a Meta app

   Create an app at developers.facebook.com and put its App ID and App Secret in FACEBOOK_APP_ID and FACEBOOK_APP_SECRET. See the Meta app setup guide for details.

2. 2

   Register the redirect URI

   Add your callback URL to the Facebook Login settings (for example https://example.uz/auth/facebook/callback). login_url() and exchange_code() must receive exactly the same URL, character for character.

3. 3

   Request permissions

   Reading Pages and the linked Instagram account needs pages_show_list and instagram_basic. With a Facebook Login for Business configuration you pass config_id instead of scopes.

4. 4

   Send the user to the login dialog

   fb.login_url(...) returns the link. Store state in the session and compare it in the callback — the SDK does not store it.

5. 5

   Get the token and Pages in the callback

   exchange_code() swaps the code for a long-lived user token, and pages() returns Pages with their Page tokens and linked Instagram IDs.

Build the login link

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)     # store it in the session
url = fb.login_url(
    redirect_uri=REDIRECT_URI,
    state=state,
    scopes=["pages_show_list", "instagram_basic"],
)
print(url)

Callback: token, Pages and the Instagram profile

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), "posts")


asyncio.run(handle_callback(code="the code parameter from the callback URL"))

Try it without code: the Playground

Next steps before production

• ▸Set a stable SOCIALIFT_INSTANCE_ID in containers — see Authentication.
• ▸Handle AuthError, PermissionError and RateLimitError separately — see Errors.
• ▸Verify webhook signatures against the raw body — see Webhooks.
• ▸Track token expiry with TokenBundle.expires_at and is_expiring().
• ▸Every method and parameter is listed in the SDK reference pages.