Facebook Pages API
This Facebook Pages API guide shows how to connect Pages, discover the accountId for each Page, and publish text, images, videos, Facebook Reels, Facebook Stories, link preview posts, and drafts. It preserves the exact fields, media rules, limits, and reconnection checks needed to implement the documented contract.
Overview and Pages-only scope
The documented flow creates posts on Facebook Pages and manages the underlying authorization steps for you. Authorization uses OAuth, exchanges for a long-lived token, and then derives separate Page tokens, which is how Meta models Page access. Scope is limited to Pages. Personal profiles are outside this contract because Meta deprecated that Graph API route, leaving manual posting in the Facebook interface as the alternative. Before any publish call, confirm the destination is a Page integration, the media address is reachable over HTTP or HTTPS, and the payload respects the format limits in the tables below.
Connect Facebook Pages
Send the request shown in Connect Facebook Pages request. The reply shape appears in Connect Facebook Pages response and contains a url. Send the user to that address. Meta presents its consent interface, where the person picks Pages they are willing to share. Once authorization finishes, a single eligible Page is linked without further prompting. With several eligible Pages, a chooser appears and each chosen Page becomes its own integration. Consent determines the accessible set; the chooser determines which members of that set are stored. If url is absent or consent is declined, stop and restart connection rather than attempting to publish.
Build your own Page-selection screen
For an in-app chooser, begin with headless=true plus redirectUri, as illustrated in Headless Facebook connection request. When multiple Pages exist, control returns to the address pattern in Page-selection callback URL, carrying status=selection_required, platform=facebook, and selectionToken. Exchange that token through Get pending Facebook Page choices, render the accounts array, and collect the user's picks. Preserve each pick's id, for example page:123456789, then pass the collection as selectedAccountIds to Save selected Facebook Pages. The resulting integrations[].id values become accountId for later posts. Treat selectionToken as brief-lived and single-use. A lone eligible Page skips the chooser and redirects without status=selection_required. Reusing or missing the token window requires starting the headless request again.
Find your account IDs
Use List Facebook integrations request after connection. Every returned object matches Facebook integration entry, exposing id, platform, platformUserId, displayName, imageUrl, and createdAt. Publishing uses id in the accountId position. Three Pages therefore yield three separate integrations from one connection. Grouping them under a profile is optional and can simplify per-user handling. An empty result for platform=facebook means no Page was stored, so inventing an accountId will not work.
Publish a post, text, and link preview
The Publish a Facebook post request demonstrates the core call: content, a platforms entry with platform facebook and accountId, and publishNow true. Inspect Publish a Facebook post response for success, status published, and the nested platformPostId and platformPostUrl. Text alone needs only content. For a link preview, follow Link preview post request and supply platformSpecificData.link; Facebook reads Open Graph data at that address to build the card. Media presence cancels link handling, so choose one approach per post. Always branch on the returned status and per-platform success value instead of assuming delivery.
Single image, photo carousel, and altText
One image belongs in a single image mediaItem, as in Single image post request body, with content serving as caption. Between two and ten images form a photo carousel, shown in Photo carousel post request body; each file is first uploaded unpublished, then combined into one feed item. Accessibility text goes in altText on individual image items, per Image alt text post request body. That field applies to single and carousel photos only, while videos and Stories disregard it. Exceeding ten images or combining video with images breaks the stated limits, so split such content across separate posts.
Video, custom thumbnail, videoThumbnailUrl, and isAiGenerated
A feed video uses one video mediaItem, as in Video post request body. Facebook retrieves the hosted file itself, suitable for MP4 files of a few hundred megabytes, and content acts as the description. A custom cover can be supplied through the video item's thumbnail field, illustrated in Video post with custom thumbnail request body, and is applied after publication in a second step. Older integrations may instead set platformSpecificData.videoThumbnailUrl; when both locations are present, videoThumbnailUrl wins. Cover handling is optional and forgiving: a bad address, excessive size, or transient network problem leaves the published video intact with an automatically chosen frame, and the error is only logged. Non-video posts ignore thumbnails entirely. Disclosure for synthetic media is controlled by isAiGenerated, shown in AI-generated video disclosure request body. It is accepted for feed videos, Reels, and video Stories, and rejected for photos, carousels, text, and image Stories. Validate encoding against the Video specifications table first.
Facebook Reels
Facebook Reels are selected with platformSpecificData.contentType set to reel, as in Facebook Reels post request body. Supply a single video at a public HTTP or HTTPS address. The content field becomes the Reel description, and a portrait 9:16 shape is advised while Meta checks file, length, and encoding constraints. Draft Reels are possible with published false, and future delivery uses scheduledFor together with timezone. Images, multiple videos, or private addresses do not satisfy this format.
Facebook Stories
Facebook Stories require platformSpecificData.contentType set to story, as in Facebook Stories post request body; leaving it out yields a feed post. Exactly one publicly reachable image or video is required. Video Stories use type video with a direct file address. JPEG or PNG images and MP4 or MOV videos are the documented choices, with 1080 by 1920 advised. Meta checks size, length, and encoding. Lifetime is 24 hours. Captions, link previews, and custom thumbnails have no effect, and stickers cannot be added. The published:false option is invalid here, though scheduledFor and timezone can still schedule a Story. Replies carry platformPostId, while platformPostUrl appears only if Facebook supplies a corresponding Story address, which may lag or disappear after expiry. Absence of that URL alone should not be read as failure when platformPostId exists.
Draft and unpublished mode
Draft creation uses published false inside platformSpecificData, as in Draft post platform-specific data. This leaves the item unpublished on the Page for staging or later completion in Facebook's composer. Stories are the exception and reject that setting. When a Story draft attempt fails, remove published false and instead save a draft or schedule with scheduledFor and timezone.
Platform-Specific Data and limits
Consult the Platform-Specific Data table for the authoritative field map covering contentType, link, isAiGenerated, published, and videoThumbnailUrl, including type, requiredness, allowed values, and constraints. Consult the Limits table for maximum text length, image and video counts, media mixing, and GIF handling. Use both tables to decide among feed, Reel, Story, and draft: contentType drives Reel and Story selection, those formats demand exactly one media item, and several fields are ignored depending on format.
Tokens and reconnection
Stored Page tokens come from a long-lived user token, so expiry is not expected during ordinary use. Reconnection becomes necessary after app revocation in Facebook Settings, a password change, a security checkpoint, or removal and re-addition of the integration. Such failures surface as OAuthException code 190, after which the integration is flagged and retries cease. Read tokenStatus.reconnectRequired and its reason, prompt the user to reconnect, and restart the connect flow. Checkpoint cases use code 190 with subcode 459 and a message directing the user to facebook.com. In that situation, reconnecting first will not help; the person must sign in at facebook.com, resolve the prompt, and only then reconnect the Page. Never keep posting to an integration flagged reconnectRequired.
| Specification | Facebook recommendation or limit |
|---|---|
| Container | MP4 or MOV recommended |
| Video and audio | H.264 video with AAC audio recommended |
| Frame rate | 30 FPS or lower recommended |
| Dimensions | Maximum 4,000 px wide; dimensions divisible by 16 recommended |
| Duration | 240 minutes maximum |
| File size | 4 GB maximum |
Source-documented parity specification; Meta validates current file, duration, and encoding limits at publish time.
| Field | Type | Required | Values and constraints | Description |
|---|---|---|---|---|
| contentType | string | No | reel, story | Set to "reel" to publish exactly one video as a Facebook Page Reel, or "story" to publish exactly one image or video as a Story. Omit for a feed post. Stories expire after 24 hours; captions, links, and custom thumbnails are ignored. published: false is not supported for Stories. |
| link | string | No | Format: uri | When provided on a text-only post, Facebook renders a link preview card from this URL's Open Graph tags. Ignored when mediaItems are attached. |
| isAiGenerated | boolean | No | — | Self-discloses that the uploaded video is AI-generated. Supported for Facebook Page feed videos, Reels, and video Stories; it is not applied to text, photo, or carousel posts. |
| published | boolean | No | — | When false, the post is created on the Page in unpublished/draft state — useful for staging or scheduling via Facebook's own composer. Defaults to true. |
| videoThumbnailUrl | string | No | Format: uri | Video posts only. Optional Facebook-specific override for mediaItems[].thumbnail. Applied as a follow-up call after publish — if the upload fails, the post still succeeds (Facebook just auto-picks a frame). Ignored when no video is attached. |
Exact source field map preserved for parity drafting.
| Limit | Value |
|---|---|
| Text length | 63,206 characters (Meta's hard cap) |
| Images per post | 10 |
| Videos per post | 1 |
| Mixing video + images | Not allowed in one post |
| GIFs | Not supported — convert to image or video first |
Source-documented parity specification.
Frequently asked questions
Can this API publish to a personal Facebook profile?
No. This contract targets Facebook Pages only. Personal-profile posting through the Graph API is described as deprecated and unavailable to most apps, so use the Facebook UI manually for a personal account.
How do I choose between a feed post, a Reel, and a Story?
Set platformSpecificData.contentType to reel with exactly one public video, or to story with exactly one public image or video. Omit contentType for a feed post. Stories expire after 24 hours and reject published:false.
What should I do when Facebook returns OAuthException code 190?
Check tokenStatus.reconnectRequired on the integration. An OAuthException with code 190 marks it for re-authentication and stops retries. For subcode 459, the user must clear the checkpoint at facebook.com before reconnecting.
curl {{API_BASE_URL}}/v1/connect/facebook \
-H "x-access-key: YOUR_API_KEY"{
"url": "https://www.facebook.com/v23.0/dialog/oauth?..."
}curl "{{API_BASE_URL}}/v1/connect/facebook?headless=true&redirectUri=https%3A%2F%2Fyourapp.com%2Ffacebook%2Fcallback" \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/connect/integrations?platform=facebook" \
-H "x-access-key: YOUR_API_KEY"{
"id": "abc123",
"platform": "facebook",
"platformUserId": "104251038...",
"displayName": "Acme Co",
"imageUrl": "https://cdn.example.com/avatar.png",
"createdAt": "..."
}curl -X POST "{{API_BASE_URL}}/v1/posts" \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "facebook", "accountId": "abc123" }
],
"publishNow": true
}'{
"success": true,
"status": "published",
"platforms": [
{
"platform": "facebook",
"success": true,
"platformPostId": "104251038_998877665",
"platformPostUrl": "https://www.facebook.com/104251038/posts/998877665"
}
]
}curl -X POST "{{API_BASE_URL}}/v1/posts" \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "facebook",
"accountId": "abc123",
"platformSpecificData": {
"link": "https://yourapp.com/case-studies/acme"
}
}
],
"publishNow": true
}'{
"content": "A short example update.",
"platforms": [{ "platform": "facebook", "accountId": "abc123" }],
"mediaItems": [
{ "type": "image", "url": "https://cdn.example.com/photo.jpg" }
]
}{
"content": "A short example update.",
"platforms": [{ "platform": "facebook", "accountId": "abc123" }],
"mediaItems": [
{ "type": "image", "url": "https://cdn.example.com/1.jpg" },
{ "type": "image", "url": "https://cdn.example.com/2.jpg" },
{ "type": "image", "url": "https://cdn.example.com/3.jpg" }
]
}{
"content": "A short example update.",
"platforms": [{ "platform": "facebook", "accountId": "abc123" }],
"mediaItems": [
{
"type": "image",
"url": "https://cdn.example.com/blocks.jpg",
"altText": "An illustrative image."
},
{
"type": "image",
"url": "https://cdn.example.com/bridge.jpg",
"altText": "An illustrative image."
}
]
}{
"content": "A short example update.",
"platforms": [{ "platform": "facebook", "accountId": "abc123" }],
"mediaItems": [
{ "type": "video", "url": "https://cdn.example.com/walkthrough.mp4" }
]
}{
"content": "A short example update.",
"platforms": [{ "platform": "facebook", "accountId": "abc123" }],
"mediaItems": [
{
"type": "video",
"url": "https://cdn.example.com/walkthrough.mp4",
"thumbnail": "https://cdn.example.com/cover.jpg"
}
]
}{
"platformSpecificData": { "isAiGenerated": true },
"mediaItems": [
{ "type": "video", "url": "https://cdn.example.com/generated-video.mp4" }
]
}{
"content": "A short example update.",
"mediaItems": [
{ "type": "video", "url": "https://cdn.example.com/reel.mp4" }
],
"platforms": [
{
"platform": "facebook",
"accountId": "abc123",
"platformSpecificData": { "contentType": "reel" }
}
],
"publishNow": true
}{
"content": "",
"mediaItems": [
{ "type": "image", "url": "https://cdn.example.com/story.jpg" }
],
"platforms": [
{
"platform": "facebook",
"accountId": "abc123",
"platformSpecificData": { "contentType": "story" }
}
],
"publishNow": true
}{
"platformSpecificData": { "published": false }
}{
"id": "abc123",
"platform": "facebook",
"platformUserId": "104251038...",
"displayName": "Acme Co",
"imageUrl": "{{MEDIA_BASE_URL}}/...",
"createdAt": "..."
}