Facebook API integration
Socialift sits on the Facebook Graph API and gathers the core Page operations into one Python SDK: OAuth and Page tokens, posts and comments, post insights, Lead Ads forms and leads, ads and targeting through the Marketing API, and verification of Meta webhook signatures.
Updated:
What is the Facebook Graph API?
The Graph API is Meta's primary interface. Within the permissions a user grants, it gives an application access to Pages, posts, comments, advertising leads and insights. The Instagram API is built on the same Graph API, which is why a Facebook integration often doubles as the foundation for Instagram.
Starting with Facebook is usually the pragmatic choice: the user goes through OAuth once, and back comes the list of their Pages together with the Instagram accounts linked to them. From there each Page's own token (page.access_token) serves both that Page and its linked Instagram account.
What is available on the Facebook side
Pages and tokens
The user's Page list, Page tokens and the Instagram accounts attached to them.
Ads and targeting
Marketing API: ad accounts, interest and location search, reach estimates without spending, campaigns, ad sets, creatives, custom and lookalike audiences.
Posts and comments
Publish, read and delete; reply to comments and hide them.
Lead Ads
Lead form listings and submitted lead payloads, paired with the leadgen webhook.
Post insights
Post statistics via post_insights. Page-level insights and Facebook audience demographics are not in the SDK (demographics exist for Instagram: ig.demographics). In 2025 Meta replaced impressions metrics with views (post_media_view).
Webhooks
Comment (feed) and leadgen events: verify_request checks the signature, parse_events splits them, dedupe_key catches repeats. There is no Messenger integration.
Fetching Pages
After the OAuth callback, one call returns both the Pages and the Instagram accounts linked to them.
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 callbackPage stories: two steps for photos, three phases for video
A Page story is not an ordinary post and never goes through the feed edge. Photos go to photo_stories, video to video_stories, and reading happens via GET /{page-id}/stories. The SDK collapses both flows into one call.
import asyncio
from socialift import Facebook
async def main(page_id: str, page_token: str):
async with Facebook.from_env() as fb:
photo = await fb.publish_photo_story(page_id, page_token,
photo_url="https://cdn.your-domain/story.jpg")
print(photo["post_id"])
video = await fb.publish_video_story(page_id, page_token,
video_url="https://cdn.your-domain/story.mp4")
print(await fb.video_story_status(video["video_id"], page_token))
print(len(await fb.stories(page_id, page_token, limit=25)))
asyncio.run(main("PAGE_ID", "PAGE_TOKEN"))Photos take two steps because the photo_stories edge accepts only a photo_id, never a URL. The image is first uploaded **unpublished** with POST /{page-id}/photos?published=false&url=... (it does not appear in the feed and survives on Meta's servers for roughly 24 hours), and the returned photo_id is then published as the story.
Video requires Meta's own resumable upload protocol, which means three phases: upload_phase=start opens a session and returns a video_id and an upload_url (pointing at rupload.facebook.com), the file or URL is then sent to that address, and upload_phase=finish publishes the story. The second step's response does not mean the upload finished, so before finish the SDK waits for uploading_phase.status == "complete" — fb.video_story_status(...) exposes that state.
The permissions are the same for all three operations: pages_manage_posts, pages_read_engagement, pages_show_list. On top of that the token holder must hold the CREATE_CONTENT task on the Page — an admin role alone is not enough here.
Video requirements: .mp4, 9:16 ratio, 540x960 to 1080x1920, 24–60 FPS, H.264 or H.265, AAC audio at 48 kHz. On duration, Meta's documentation contradicts itself — one page says “3 to 90 seconds”, another says a video story “can not exceed 60 seconds”; the safe range is 3–60 seconds.
Common traps in Facebook integrations
- If “Require App Secret” is enabled in the app settings, calls without appsecret_proof fail — the SDK adds it to every request.
- A Page token is not a user token: actions are performed with the Page token.
- Campaigns, ad sets and ads are created PAUSED and budgets are given in major currency units — confirm the launch as a separate step.
- Under Standard Access, permissions only work for people with a role on the app (admin, developer, tester); everyone else needs Advanced Access — App Review plus Business Verification.
- A Page token is tied to one Page + admin + app combination: if that person changes their password, removes the app or loses their Page role, the token stops working.
Frequently asked questions
Can Facebook ads be managed through the API?
Yes. The Meta Marketing API creates campaigns, ad sets, ads and creatives, searches interests and locations for targeting, and estimates reach without spending. When audiences are built from customer emails and phone numbers, the data is SHA-256 hashed on your own server where the SDK runs.
Do Facebook and Instagram need separate integrations?
Not necessarily. With Facebook Login one OAuth flow returns both the Pages and the Instagram professional accounts linked to them. For an Instagram account without a Page, the SDK offers Instagram Login: Instagram(app_id, app_secret). Either way the account must be Business or Creator.
Is App Review mandatory to use the Facebook API?
Not if only people with a role on the app (admins, developers, testers) use it — Standard Access covers them. To work with other people's Pages, each permission needs Advanced Access, which requires App Review and Business Verification.
Can I publish Facebook Page stories through the API?
Yes, through the Page Stories API. A photo takes two steps: upload it as an unpublished photo (published=false), then pass the resulting photo_id to the photo_stories edge, which does not accept a URL. Video needs a three-phase resumable upload (upload_phase=start → send the file to upload_url → upload_phase=finish). You need pages_manage_posts, pages_read_engagement and pages_show_list, plus the CREATE_CONTENT task on the Page for the token holder. In the SDK this is fb.publish_photo_story(...) and fb.publish_video_story(...).
Can I read Facebook Messenger messages through Socialift?
No. Socialift has no Facebook Messenger integration: the SDK does not read Messenger conversations or reply to them. For Meta messaging it supports Instagram Direct — via ig.conversations and ig.send_message.