Skip to content

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.

Video specifications
SpecificationFacebook recommendation or limit
ContainerMP4 or MOV recommended
Video and audioH.264 video with AAC audio recommended
Frame rate30 FPS or lower recommended
DimensionsMaximum 4,000 px wide; dimensions divisible by 16 recommended
Duration240 minutes maximum
File size4 GB maximum

Source-documented parity specification; Meta validates current file, duration, and encoding limits at publish time.

Platform-Specific Data
FieldTypeRequiredValues and constraintsDescription
contentTypestringNoreel, storySet 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.
linkstringNoFormat: uriWhen provided on a text-only post, Facebook renders a link preview card from this URL's Open Graph tags. Ignored when mediaItems are attached.
isAiGeneratedbooleanNo—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.
publishedbooleanNo—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.
videoThumbnailUrlstringNoFormat: uriVideo 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.

Limits
LimitValue
Text length63,206 characters (Meta's hard cap)
Images per post10
Videos per post1
Mixing video + imagesNot allowed in one post
GIFsNot 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.

Connect Facebook Pages request
curl {{API_BASE_URL}}/v1/connect/facebook \
  -H "x-access-key: YOUR_API_KEY"
Connect Facebook Pages response
{
	"url": "https://www.facebook.com/v23.0/dialog/oauth?..."
}
Headless Facebook connection request
curl "{{API_BASE_URL}}/v1/connect/facebook?headless=true&redirectUri=https%3A%2F%2Fyourapp.com%2Ffacebook%2Fcallback" \
  -H "x-access-key: YOUR_API_KEY"
List Facebook integrations request
curl "{{API_BASE_URL}}/v1/connect/integrations?platform=facebook" \
  -H "x-access-key: YOUR_API_KEY"
Facebook integration entry
{
	"id": "abc123",
	"platform": "facebook",
	"platformUserId": "104251038...",
	"displayName": "Acme Co",
	"imageUrl": "https://cdn.example.com/avatar.png",
	"createdAt": "..."
}
Publish a Facebook post request
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
  }'
Publish a Facebook post response
{
	"success": true,
	"status": "published",
	"platforms": [
		{
			"platform": "facebook",
			"success": true,
			"platformPostId": "104251038_998877665",
			"platformPostUrl": "https://www.facebook.com/104251038/posts/998877665"
		}
	]
}
Link preview post request
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
  }'
Single image post request body
{
	"content": "A short example update.",
	"platforms": [{ "platform": "facebook", "accountId": "abc123" }],
	"mediaItems": [
		{ "type": "image", "url": "https://cdn.example.com/photo.jpg" }
	]
}
Photo carousel post request body
{
	"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" }
	]
}
Image alt text post request body
{
	"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."
		}
	]
}
Video post request body
{
	"content": "A short example update.",
	"platforms": [{ "platform": "facebook", "accountId": "abc123" }],
	"mediaItems": [
		{ "type": "video", "url": "https://cdn.example.com/walkthrough.mp4" }
	]
}
Video post with custom thumbnail request body
{
	"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"
		}
	]
}
AI-generated video disclosure request body
{
	"platformSpecificData": { "isAiGenerated": true },
	"mediaItems": [
		{ "type": "video", "url": "https://cdn.example.com/generated-video.mp4" }
	]
}
Facebook Reels post request body
{
	"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
}
Facebook Stories post request body
{
	"content": "",
	"mediaItems": [
		{ "type": "image", "url": "https://cdn.example.com/story.jpg" }
	],
	"platforms": [
		{
			"platform": "facebook",
			"accountId": "abc123",
			"platformSpecificData": { "contentType": "story" }
		}
	],
	"publishNow": true
}
Draft post platform-specific data
{
	"platformSpecificData": { "published": false }
}
Response example 6
{
	"id": "abc123",
	"platform": "facebook",
	"platformUserId": "104251038...",
	"displayName": "Acme Co",
	"imageUrl": "{{MEDIA_BASE_URL}}/...",
	"createdAt": "..."
}