Docs/API Reference/Facebook

Facebook API

Use the Crosspostify API to publish videos, photos, multi-photo posts, Stories, and text posts to Facebook Pages — including first comments, text formatting presets, AI labels, and scheduling.

Post Types

Video · Photo · Multi-photo · Story · Text

First Comment

Supported

Text Formatting

Presets supported

Account Type

Facebook Pages only

Facebook is the world's largest social network. The Crosspostify Facebook API integration supports publishing to Facebook Pages — with unique features like first comment automation and text formatting presets that are exclusive to Facebook.

This page covers everything specific to Facebook when using the Crosspostify API. For general authentication, rate limits, and error handling, see the full API Reference.

Facebook-Specific Parameters

Facebook supports two exclusive parameters not available on other platforms: facebookFirstComment and textFormatPresetId. facebookFirstComment works on every post type except Stories; textFormatPresetId only on /post/text.

accountId✓ AppliesRequired. The id of the connected Facebook Page from GET /social-accounts (Crosspostify's account ID, not the Facebook Page ID).

caption✓ AppliesOptional on media posts, required on /post/text. The post text (not shown on Stories). Markdown links [text](url) become "text url".

facebookFirstComment✓ AppliesFacebook only. Posts a first comment after publishing (not on Stories).

textFormatPresetId✓ AppliesFacebook only, /post/text only. Numeric background preset ID.

is_aigc✓ AppliesOptional. Adds Facebook's AI label to Reels and video Stories (not applied if the video falls back to a normal Page video). Ignored for photos and text.

facebook✓ AppliesOptional object: post as a Story. See Facebook Settings below.

title✗ IgnoredNot used for Facebook — ignored.

boardId✗ IgnoredPinterest only — ignored for Facebook.

link✗ IgnoredPinterest and Tumblr only — ignored for Facebook. Put links in the caption or the first comment.

thumbnailTimestamp✗ IgnoredTikTok only — ignored for Facebook.

tiktok / instagram / youtube✗ IgnoredTikTok / Instagram / YouTube only — ignored for Facebook.

Facebook Settings

Add an optional facebook object to a post to publish it as a Page Story instead of a feed post.

as_story and the top-level is_aigc accept true/false, the strings "true"/"false" (any case) and 1/0. Any other value is rejected with HTTP 400, for example "Invalid facebook.as_story".

facebook.as_storybooleanoptional

Publish as a Page Story (visible for 24 hours). Works with /post/image (one image), /post/video (one video; Facebook's limit is 60 seconds) and /post/images with exactly one image. Stories show no caption or link, and facebookFirstComment is skipped. Default: false.

Good to know

A published Story has no lasting post URL (it disappears after 24 hours), so postUrl stays empty.
is_aigc: true adds the AI label to video Stories as well (photo Stories get no AI label).
as_story: true on /post/images with more than one image is rejected with HTTP 400: "A Story takes exactly one image or one video". A facebook value that is not an object is rejected too ("Invalid facebook settings").

Example: post a video as a Story

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_12345",
    "posts": [
      {
        "accountId": "acc_facebook_789",
        "caption": "",
        "is_aigc": false,
        "facebook": {
          "as_story": true
        }
      }
    ]
  }'

Supported Endpoints

Facebook supports all four posting endpoints, including text-only posts with /post/text (available for Facebook and Threads only):

Facebook Pages only

The Crosspostify API publishes to Facebook Pages, not personal profiles. Personal Facebook profiles are not supported by the Facebook Graph API for third-party publishing.

POST/post/video

Publish a video to a Facebook Page. Supports scheduling and the Facebook options facebookFirstComment, is_aigc and facebook.as_story.

Facebook Video Notes

Upload your video first via POST /media and use the returned mediaId
Use facebookFirstComment to automatically post a comment right after publishing
Recommended aspect ratio: 16:9 (landscape) or 9:16 (vertical) for Reels-style
Videos are published as Reels; if Facebook does not accept the video as a Reel, it is posted as a normal Page video instead (without the AI label)
Set is_aigc: true to add Facebook's AI label (Reels and video Stories); set facebook.as_story: true to post the video as a Story (Facebook's limit: 60 seconds)
scheduledDate takes any ISO 8601 date-time: Z or an offset such as +01:00 (converted to UTC). Without an offset it is read as UTC.
Omit scheduledDate to post immediately

Request Body

mediaIdstringrequired

The ID of the uploaded video file. Obtain this from POST /media.

scheduledDatestringoptional

Optional. A future ISO 8601 date-time, e.g. 2030-01-15T10:00:00Z. Offsets such as +01:00 are converted to UTC; a value without offset is read as UTC. Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects. Include one object per Facebook Page you want to post to.

posts[].accountIdstringrequired

The id of the connected Facebook Page from GET /social-accounts (Crosspostify's account ID, not the Facebook Page ID).

posts[].captionstringoptional

Optional (default empty). The video description shown on the post (not on Stories). Cut to 2,200 characters without an error.

posts[].facebookFirstCommentstringoptional

Text to post as the first comment right after publishing (not for Stories). Facebook only.

posts[].is_aigcbooleanoptional

Set to true to add Facebook's AI label to the Reel or video Story (not applied if the video falls back to a normal Page video). Default: false.

posts[].facebookobjectoptional

Facebook settings: as_story (post the video as a Story; Facebook's limit is 60 seconds). See Facebook Settings.

Response (202 Accepted)

{ "mediaId": "vid_12345", "message": "Video post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "facebook", "socialAccountId": "acc_facebook_789", "status": "SCHEDULED" } ] }

status is SCHEDULED when scheduledDate is set, otherwise QUEUED. Publishing happens afterwards: check the result with GET /posts?id=<id>.

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_facebook_789",
        "caption": "Check out our latest video! 🎬 #facebook",
        "facebookFirstComment": "What do you think? Drop a comment below! 👇"
      }
    ]
  }'

POST/post/image

Publish a single photo to a Facebook Page feed.

Facebook Photo Notes

Facebook accepts most common aspect ratios without cropping
Recommended dimensions: at least 1200×630px for best feed display
Images are sent as JPEG, compressed to max 4 MB (dimensions unchanged)
Use facebookFirstComment to seed engagement with a first comment
Set facebook.as_story: true to post the image as a Story
scheduledDate takes any ISO 8601 date-time: Z or an offset such as +01:00 (converted to UTC). Without an offset it is read as UTC.

Request Body

mediaIdstringrequired

The ID of the uploaded image file. Obtain this from POST /media.

scheduledDatestringoptional

Optional. A future ISO 8601 date-time, e.g. 2030-01-15T10:00:00Z. Offsets such as +01:00 are converted to UTC; a value without offset is read as UTC. Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects. Include one object per Facebook Page.

posts[].accountIdstringrequired

The id of the connected Facebook Page from GET /social-accounts (Crosspostify's account ID, not the Facebook Page ID).

posts[].captionstringoptional

Optional (default empty). The photo caption shown on the post (not on Stories). Cut to 2,200 characters without an error.

posts[].facebookFirstCommentstringoptional

Text to post as the first comment right after publishing (not for Stories). Facebook only.

posts[].facebookobjectoptional

Facebook settings: as_story (post the image as a Story). See Facebook Settings.

Response (202 Accepted)

{ "mediaId": "img_12345", "message": "Image post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "facebook", "socialAccountId": "acc_facebook_789", "status": "SCHEDULED" } ] }

status is SCHEDULED when scheduledDate is set, otherwise QUEUED. Publishing happens afterwards: check the result with GET /posts?id=<id>.

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/image" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "img_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_facebook_789",
        "caption": "Beautiful day at the office 🌟",
        "facebookFirstComment": "Tag someone who needs to see this!"
      }
    ]
  }'

POST/post/images

Publish a multi-photo post to a Facebook Page. Facebook displays multiple images as a photo album or inline gallery in the feed.

Facebook Multi-Photo Notes

1 to 10 images per post; a single image is posted as a normal photo
Images are displayed in the order provided in mediaIds
Facebook renders multiple images as an inline gallery in the feed
Images are sent as JPEG, compressed to max 4 MB each (dimensions unchanged)
Multi-photo posts cannot be posted as a Story; with exactly one image, facebook.as_story: true posts it as a photo Story
Use facebookFirstComment to add context or a CTA below the post
scheduledDate takes any ISO 8601 date-time: Z or an offset such as +01:00 (converted to UTC). Without an offset it is read as UTC.

Request Body

mediaIdsarrayrequired

Ordered array of 1 to 10 image media IDs. Images appear in this order in the gallery. A single image is posted as a normal photo.

scheduledDatestringoptional

Optional. A future ISO 8601 date-time, e.g. 2030-01-15T10:00:00Z. Offsets such as +01:00 are converted to UTC; a value without offset is read as UTC. Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects. Include one object per Facebook Page.

posts[].accountIdstringrequired

The id of the connected Facebook Page from GET /social-accounts (Crosspostify's account ID, not the Facebook Page ID).

posts[].captionstringoptional

Optional (default empty). The gallery caption shown on the post. Cut to 2,200 characters without an error.

posts[].facebookFirstCommentstringoptional

Text to post as the first comment right after publishing (not for Stories). Facebook only.

posts[].facebookobjectoptional

Facebook settings: as_story (only with exactly one image in mediaIds). See Facebook Settings.

Response (202 Accepted)

{ "mediaIds": ["img_001", "img_002", "img_003"], "message": "Multiple images post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "facebook", "socialAccountId": "acc_facebook_789", "status": "SCHEDULED" } ] }

status is SCHEDULED when scheduledDate is set, otherwise QUEUED. Publishing happens afterwards: check the result with GET /posts?id=<id>.

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/images" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaIds": ["img_001", "img_002", "img_003"],
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_facebook_789",
        "caption": "Swipe through our latest collection 👉",
        "facebookFirstComment": "Which one is your favourite?"
      }
    ]
  }'

POST/post/textFacebook & Threads

Publish a text-only post to a Facebook Page. Optionally apply a background preset to make the post stand out in the feed. /post/text also accepts Threads accounts; the background preset is Facebook only.

Facebook Text Post Notes

No mediaId or mediaIds — this is a text-only post
caption is required: an empty or whitespace-only caption returns HTTP 400 "Missing caption"
Use textFormatPresetId (a numeric preset ID) to apply a background to the post
Facebook may show long texts without the background, so keep the text short when you use a preset
Use facebookFirstComment to add a CTA or link in the first comment
scheduledDate takes any ISO 8601 date-time: Z or an offset such as +01:00 (converted to UTC). Without an offset it is read as UTC.

Request Body

scheduledDatestringoptional

Optional. A future ISO 8601 date-time, e.g. 2030-01-15T10:00:00Z. Offsets such as +01:00 are converted to UTC; a value without offset is read as UTC. Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects. Include one object per Facebook Page.

posts[].accountIdstringrequired

The id of the connected Facebook Page from GET /social-accounts (Crosspostify's account ID, not the Facebook Page ID).

posts[].captionstringrequired

The text of the post. Empty or whitespace-only text returns HTTP 400 "Missing caption". Cut to 2,200 characters without an error. Keep it short if you use textFormatPresetId.

posts[].textFormatPresetIdstring | integeroptional

Numeric Facebook background preset ID, e.g. "106018623298955" (send it as a string). Leave it out or send "" for a plain text post; anything that is not a number returns HTTP 400 "Invalid textFormatPresetId". See Text Formatting below.

posts[].facebookFirstCommentstringoptional

Text to post as the first comment right after publishing. Facebook only.

Response (202 Accepted)

{ "message": "Text-only post scheduled successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "facebook", "socialAccountId": "acc_facebook_789", "status": "SCHEDULED" } ] }

Without scheduledDate the message is "Text-only post created successfully" and status is QUEUED. Publishing happens afterwards: check the result with GET /posts?id=<id>.

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/text" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_facebook_789",
        "caption": "Big announcement coming tomorrow. Stay tuned! 👀",
        "textFormatPresetId": "106018623298955",
        "facebookFirstComment": "Set a reminder so you do not miss it!"
      }
    ]
  }'

First Comment

The facebookFirstComment parameter lets you automatically post a comment on your own post immediately after it goes live. This is a popular strategy for boosting engagement — for example, putting hashtags or a link in the first comment rather than the caption.

Common use cases

Add hashtags without cluttering the caption
Include a link (e.g. "Link in first comment")
Seed a question to drive replies
Add a CTA after the post goes live
Share a discount code or promo link

How it works

Comment is posted by the Page itself
Posted right after the main post goes live
Works on video, photo, multi-photo and text posts (not Stories)
Plain text only — no media attachments
Leading/trailing spaces are removed; an empty value posts no comment
If the comment fails, the post itself stays published

Text Formatting Presets

Facebook allows text-only posts to have a visual background style applied via textFormatPresetId (on /post/text only). These presets render the post with a colored or patterned background, making it stand out in the feed. Leave textFormatPresetId out (or send "") for a plain text post.

Keep the text short

Facebook may show long texts without the background, even when a preset is set. Use presets for short statements.

Available Preset IDs

Send the ID as a string (e.g. "106018623298955") to avoid number precision issues.

106018623298955Solid purple

365653833956649Pink tropical plants

618093735238824Brown illustration

1917619914913753D hearts

21936277939854153D heart eyes emojis

2005213374653063D flame emojis

1821844087883360Walking yellow illustration

177465482945164Light purple 3D cube pattern

160419724814650Orange with pink illustration

2486239024012503D smiling emoji

2404018167717063D rose emojis

18688559434173603D crying laughter emoji

255989551804163Eye pink illustration

1654916007940525Light grey illustration

1679248482160767Light blue illustration

518948401838663Pink heart pattern

423339708139719Illustration

204187940028597Solid red

621731364695726Solid red

518596398537417Red illustration

134273813910336Tree red illustration

217321755510854Pink/purple hearts on pink

323371698179784Sunset red illustration

901751159967576Gradient dark orange/red

552118025129095Brown illustration

263789377694911Apple red illustration

606643333067842Tulip light orange illustration

458988134561491Cat dark orange illustration

548109108916650Unicorn red illustration

175493843120364Pink/yellow gradient

338976169966519Stairs beige illustration

206513879997925Spiral beige illustration

168373304017982Cube beige illustration

1271157196337260Solid red

174496469882866Lemon yellow illustration

862667370603267Egg light yellow illustration

127541261450947Ball green illustration

218067308976029Light grey illustration

688479024672716Gradient teal/light green

238863426886624Cat light blue illustration

301029513638534Solid teal

154977255088164Solid teal

1941912679424590Gradient grey/dark grey

396343990807392Flower teal illustration

143093446467972Blue clouds on dark blue

161409924510923Rocket heart in the sky

145893972683590Solid dark purple

217761075370932Solid blue

931584293685988Wave blue illustration

148862695775447Pink/purple hearts on purple

100114277230063Deep sea blue illustration

558836317844129Spiral purple illustration

172497526576609Watermelon light purple

433967226963128Solid purple

197865920864520Donut light purple

643122496026756Pink illustration

762009070855346Balloon light grey illustration

228164237768720Grey hearts on black

146487026137131Rain black illustration

221828835275596Glasses light grey illustration

1903718606535395Solid red

1881421442117417Solid black

249307305544279Gradient red/blue

1777259169190672Gradient purple/magenta

303063890126415Yellow/orange/pink gradient

122708641613922Gradient dark grey/black

319468561816672Dark blue illustration

121945541697934Pink illustration

288211338285858Blue illustration

446330032368780Gradient red

219266485227663Solid magenta

1289741387813798Solid dark red

1365883126823705Solid blue

Preset availability may vary

Facebook periodically updates available text format presets. Non-numeric IDs are rejected with HTTP 400 ("Invalid textFormatPresetId"). Numeric IDs are passed to Facebook as they are; if Facebook does not accept an ID, the post fails (see error in GET /posts). The same list is in the API Reference.

Content Guidelines

Facebook accepts a wide range of media formats and is generally more lenient than Instagram on aspect ratios. However, following these recommendations ensures the best feed presentation.

Video Requirements

Format: MP4 or MOV (other formats are rejected at upload)
Max file size: 100 MB via Crosspostify
Recommended ratio: 16:9 or 9:16
Min resolution: 720p recommended

Photo Requirements

Format: JPG, PNG or WEBP (converted to JPEG on upload)
Max file size: 20 MB via Crosspostify
Recommended: 1200×630px (1.91:1)
Most aspect ratios accepted without cropping
Min width: 600px recommended

Caption Best Practices

Max 2,200 characters (longer text is cut)
Hashtags supported but less impactful than on Instagram
Links in captions generate link previews (write plain URLs; Markdown links are converted to 'text url')
Emojis are fully supported
Use first comment for hashtags/links instead

Scheduling

Any future time works: no minimum lead time
Published within about a minute of the scheduled time
ISO 8601 with Z or an offset (e.g. +01:00); no offset = UTC
Omit scheduledDate to post immediately
No maximum scheduling window