Instagram API integration

What is the Instagram API and what is it for?

What is supported on the Instagram side

Everything below ships with the SDK — no deep Graph API knowledge required.

Your first request — from OAuth to the Instagram account

On the Facebook Login path, once the user signs in, their Pages and the Instagram accounts linked to them come back in a single call.

import asyncio
from socialift import Facebook

async def main(code: str):
    # FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, SOCIALIFT_LICENSE_KEY
    async with Facebook.from_env() as fb:
        token = await fb.exchange_code(code, redirect_uri="https://your-domain/cb")
        for page in await fb.pages(token.access_token):
            print(page.name, "→ instagram:", page.instagram_username)

asyncio.run(main(code="..."))  # ?code= from the OAuth callback

Reading Direct conversations

The Conversations API returns only a participant's ID and username. conversations() adds each contact's name, follower count and follow status from the User Profile API, fetched in parallel with at most 8 requests at a time.

import asyncio, os
from socialift import Instagram

async def main(page_token: str):
    async with Instagram.via_facebook(app_secret=os.environ["FACEBOOK_APP_SECRET"]) as ig:
        chats = await ig.conversations(page_token, page_id="1111", ig_user_id="2222")
        for chat in chats["data"]:
            c = chat["contact"]
            if c:
                print(c.get("name"), c.get("follower_count"), "follows us:", c.get("is_user_follow_business"))

asyncio.run(main("PAGE_TOKEN"))

How do you publish a story through the API?

A story differs from an ordinary post in exactly one way: the container carries media_type=STORIES and goes out through the same media_publish step. There is no caption — story captions are not shown. Meta's media rules: JPEG images up to 8 MB at a recommended 9:16 ratio; MOV or MP4 video, 3–60 seconds, up to 100 MB.

import asyncio, os
from socialift import Instagram

async def main(page_token: str):
    async with Instagram.via_facebook(app_secret=os.environ["FACEBOOK_APP_SECRET"]) as ig:
        story = await ig.publish_story(page_token, ig_user_id="2222",
                                       image_url="https://cdn.your-domain/story.jpg")
        print(story["media_id"])

        live = await ig.stories(page_token, ig_user_id="2222", limit=25)
        print(len(live), "stories are live right now")

asyncio.run(main("PAGE_TOKEN"))

Connecting Instagram in four steps

1. 1

   Prepare the Instagram account

   Switch the account to Business or Creator. Linking a Facebook Page is required only on the Facebook Login path; Instagram Login (Instagram(app_id, app_secret)) works without a Page.

2. 2

   Create a Facebook app

   Create an app in Meta for Developers and request only the permissions you use. For Instagram Login: instagram_business_basic plus, as needed, instagram_business_content_publish, instagram_business_manage_comments, instagram_business_manage_messages, instagram_business_manage_insights. For Facebook Login: pages_show_list, pages_read_engagement, instagram_basic plus, as needed, instagram_content_publish, instagram_manage_comments, instagram_manage_messages, instagram_manage_insights (leads_retrieval for leads). If your app serves accounts you don't own or manage, Advanced Access requires App Review and Business Verification.

3. 3

   Get a Socialift token

   Sign in with Google or email, open “Tokenlar” (Tokens) in the dashboard, press “Yangi token” (New token) and copy the key that starts with slk_. The first month is free.

4. 4

   Wire up the SDK

   pip install socialift, put the key in the SOCIALIFT_LICENSE_KEY environment variable and send your first call.

Instagram, Facebook, LinkedIn, TikTok and Telegram capabilities

Every platform runs in one SDK under one error model.

yesnoScroll the table sideways

Before you ship to production

The mistakes that show up most often in Instagram integrations.

• ▸Make sure server-side calls carry appsecret_proof: when “Require App Secret” is enabled in the app settings, Meta rejects calls without it (the SDK adds it whenever app_secret is set).
• ▸Instagram calls (except messaging) fall under Business Use Case rate limits: watch the X-Business-Use-Case-Usage header and back off on RateLimitError.
• ▸Compute the webhook signature over the raw body — re-serialising the JSON breaks the match.
• ▸The same event can arrive more than once: Meta sends no event ID, so build a key from the payload (mid, leadgen_id, comment_id — dedupe_key in the SDK) and store it in a unique column.
• ▸Instagram Login tokens last 60 days: refresh them with refresh_token once they are over 24 hours old and before they expire. Page tokens derived from a long-lived user token have no expiry date but are invalidated in certain cases, such as revoked access.
• ▸When a user revokes access you get an AuthError — surface that state in your CRM UI.