Instagram Direct API
The Instagram Direct API lets you read a business account's conversations and reply to them within the 24-hour window. Socialift normalises those calls and returns every participant with a full profile — not just an ID and username, but a name, follower count and whether they follow the business.
Updated:
What can the Instagram Direct API do?
The Instagram Messaging API lets you read and reply to a professional account's Direct conversations (Business or Creator only). Instagram Login needs instagram_business_manage_messages; Facebook Login needs instagram_manage_messages. Only the user can start a conversation, and replies follow the 24-hour window.
In practice you can build an inbox inside your own product: conversation list, recent messages, replies and routing between agents. Limits: only the 20 most recent messages per conversation can be read, Requests-folder conversations inactive for 30 days are not returned, and group chats are not supported — keep full history in your own database via webhooks.
The constraint is clear: you may reply within 24 hours of the user's last message. After that only a human agent reply tagged HUMAN_AGENT can go out, for up to 7 days, and it needs the Human Agent feature approved in App Review. The SDK's send_message sends no tag, so Meta rejects it outside the window.
What Socialift adds
Full contact profile
The Conversations API gives only a participant's ID and username. Socialift adds name, follower_count, is_user_follow_business and is_business_follow_user from the User Profile API (available once the user has messaged you).
Parallel lookups
Profile lookups run in parallel (up to 8 at a time), so 50 conversations don't mean 50 sequential requests. The SDK does not cache profiles; store them in your own database if needed.
One error model
AuthError and RateLimitError behave identically across Instagram, Facebook, LinkedIn, TikTok and Telegram, with retry_after taken from the response.
appsecret_proof
When app_secret is set, appsecret_proof is attached to every request automatically — with “Require App Secret” enabled, Meta rejects calls without it.
Reading conversations
import asyncio, os
from socialift import Instagram
async def main(page_token: str):
# Facebook Login path; with Instagram Login use Instagram.from_env() and an IG token, no page_id
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"))Sending a message and handling errors
Rate limits, a closed 24-hour window and revoked tokens are the states you will meet most often in production.
import asyncio, os
from socialift import AuthError, Instagram, PermissionError, RateLimitError
async def reply(recipient_id: str, page_token: str, text: str):
async with Instagram.via_facebook(app_secret=os.environ["FACEBOOK_APP_SECRET"]) as ig:
try:
await ig.send_message(recipient_id, page_token, text, page_id="1111")
except RateLimitError as exc:
await asyncio.sleep(exc.retry_after or 60) # then retry or queue it
except PermissionError:
... # 24-hour window closed — hand the conversation to a human agent
except AuthError:
... # token revoked → send the user back through login
asyncio.run(reply("IGSID", "PAGE_TOKEN", "Hi! Here is the answer to your question."))When designing a Direct integration
- Track the 24-hour window and move unanswered conversations into their own queue.
- Make sending idempotent so a repeated webhook does not fire a second reply.
- Mark whether a human or a bot answered — you will need it for reporting.
- Store the contact profile in your own database, but refresh the follower count periodically.
- Surface the state where a user has blocked you or revoked access.
Frequently asked questions
Can I auto-reply to Instagram Direct through the API?
Yes, within 24 hours of the user's last message. Outside that window automated messages are not allowed; only a human agent can reply with the HUMAN_AGENT tag for up to 7 days (the Human Agent feature requires App Review). Socialift's send_message sends text only and adds no tags.
What permissions does the Direct API need?
Instagram Login: instagram_business_basic and instagram_business_manage_messages. Facebook Login: instagram_basic, instagram_manage_messages and pages_show_list (on this path the account is linked to a Facebook Page). Serving accounts you don't own requires Advanced Access via App Review.
What information can I get about the person writing?
Through Socialift you get name, username, follower count, is_user_follow_business and is_business_follow_user. Meta returns the profile only after the user messaged you or tapped an icebreaker, and never for a user who blocked you. These fields feed lead qualification.
Can a business message a user first in Instagram Direct?
No. A conversation starts only when the user messages the business account — from Direct, a post, a story mention or another channel. Group chats are not supported: a professional account talks to one customer per conversation.
Do the SDK's Direct methods work during the free month?
Yes. For the first 30 days the token unlocks every SDK feature, including conversations, messages, send_message and contact. After that the token renews in 30-day periods from your balance and its features depend on the token's plan — “Tekshirish va muhitlar” (Check and environments) in the dashboard shows the exact list. The dashboard Playground works on any plan.
Sources
Related pages
Bring Direct into your own product
Get a token and pull your first conversation list through the SDK today.
Get a free token →