Facebook Page Posting API Documentation

Kavenio publishes to connected Facebook Page accounts. Use facebook as the platform value and put Facebook-specific fields in platformSpecificData. Kavenio owns normal scheduling, retry state, target status, and provider error tracking. Facebook provider-native drafts and scheduled Page posts are also available when explicitly requested.

Quick Reference

Capability	Support
Platform key	`facebook`
Feed post	Text, link, one image, one video/GIF, or multi-image feed post
Carousel feed post	2-5 `carouselCards` with matching media items
Reel	One video
Story	One image or one video, no caption
First comment	Feed and Reels after native publish
Geo restrictions	Feed and Reels
Native draft/scheduled post	Feed and Reels through `unpublishedContentType`
Multi-Page fanout	Feed posts through `multiPageTargets`
Post analytics	`GET /v1/analytics` for impressions, reach, likes, comments, shares, clicks
Native edit/unpublish	Not supported

Create A Feed Post

{
  "content": "Launch update for our Facebook Page.",
  "mediaItems": [
    {
      "type": "image",
      "url": "https://cdn.example.com/facebook-launch.jpg",
      "mimeType": "image/jpeg"
    }
  ],
  "platforms": [
    {
      "platform": "facebook",
      "accountId": "acc_123",
      "platformSpecificData": {
        "firstComment": "Full details: https://example.com/launch",
        "geoRestrictions": {
          "countries": ["US", "ES"]
        }
      }
    }
  ],
  "publishNow": true
}

kavenio posts create \
  --content "Launch update for our Facebook Page." \
  --publish-now \
  --media-url https://cdn.example.com/facebook-launch.jpg \
  --platform facebook:acc_123 \
  --first-comment "Full details: https://example.com/launch"

Feed posts support text-only posts, link posts, one photo, one video/GIF, or up to 10 images. When firstComment is supplied, Kavenio creates it after the Facebook object publishes. First comments require the connected credential to include pages_manage_engagement. Accounts connected before this permission was added must reconnect before using firstComment; Kavenio checks the stored scope before creating the main post. For feed fanout, add Page IDs available to the same connected Meta user in multiPageTargets. Kavenio creates one target per Page and tracks each result independently.

Reels

Use contentType: "reel" for Facebook Reels.

{
  "content": "Reel caption",
  "mediaItems": [
    {
      "type": "video",
      "url": "https://cdn.example.com/reel.mp4",
      "mimeType": "video/mp4"
    }
  ],
  "platforms": [
    {
      "platform": "facebook",
      "accountId": "acc_123",
      "platformSpecificData": {
        "contentType": "reel",
        "reelTitle": "Launch Reel",
        "firstComment": "Pinned follow-up"
      }
    }
  ],
  "publishNow": true
}

Reels require exactly one video media item. link and multiPageTargets are not supported for Reels.

Stories

Use contentType: "story" for Facebook Stories.

{
  "content": "",
  "mediaItems": [
    {
      "type": "image",
      "url": "https://cdn.example.com/story.jpg",
      "mimeType": "image/jpeg"
    }
  ],
  "platforms": [
    {
      "platform": "facebook",
      "accountId": "acc_123",
      "platformSpecificData": {
        "contentType": "story"
      }
    }
  ],
  "publishNow": true
}

Stories require exactly one image or video media item. Facebook Story publishing does not support captions, first comments, links, geo restrictions, provider-native drafts/scheduling, or multi-Page fanout.

Carousel Feed Posts

Use carouselCards for link-style carousel feed posts. The number of cards must match the number of media items.

{
  "content": "Choose the best fit.",
  "mediaItems": [
    { "type": "image", "url": "https://cdn.example.com/card-1.jpg" },
    { "type": "image", "url": "https://cdn.example.com/card-2.jpg" }
  ],
  "platforms": [
    {
      "platform": "facebook",
      "accountId": "acc_123",
      "platformSpecificData": {
        "carouselLink": "https://example.com/products",
        "carouselCards": [
          {
            "name": "Plan A",
            "description": "For small teams",
            "link": "https://example.com/products/a"
          },
          {
            "name": "Plan B",
            "description": "For growing teams",
            "link": "https://example.com/products/b"
          }
        ]
      }
    }
  ],
  "publishNow": true
}

Provider-Native Drafts And Scheduling

Use provider-native publishing fields only when you want Facebook to create a draft or native scheduled Page post.

{
  "content": "Native scheduled Facebook post.",
  "platforms": [
    {
      "platform": "facebook",
      "accountId": "acc_123",
      "platformSpecificData": {
        "unpublishedContentType": "scheduled",
        "scheduledPublishTime": "2027-06-16T10:00:00.000Z"
      }
    }
  ],
  "publishNow": true
}

scheduledPublishTime must be between 10 minutes and 30 days from the publish attempt. Kavenio scheduledFor is separate: it delays the Kavenio job, then the job creates the Facebook object. First comments are skipped for provider-native drafts and scheduled posts because there is no published Facebook object to comment on yet.

Platform-Specific Fields

Field	Type	Behavior
`pageId`	string	Selects a specific Page available through the connected Facebook account.
`contentType`	`"feed"` \| `"video"` \| `"reel"` \| `"story"`	Selects the Facebook publish path. Defaults to feed.
`firstComment`	string	Created after feed or Reel publish. Skipped for native drafts/scheduled posts.
`link`	URL string	Feed link post URL.
`title`	string	Video title compatibility field.
`reelTitle`	string	Reel title.
`carouselLink`	URL string	Default link for carousel cards.
`carouselCards`	array	2-5 cards. Count must match media item count.
`unpublishedContentType`	`"draft"` \| `"scheduled"`	Creates a native Facebook draft or scheduled post.
`scheduledPublishTime`	ISO datetime	Required for native scheduled posts.
`geoRestrictions`	object	Country, region, or city targeting for supported publish paths.
`multiPageTargets`	string[]	Additional Page IDs for independently tracked feed-post fanout.

Compatibility aliases:

Alias	Canonical field
`draft: true`	`unpublishedContentType: "draft"`
`geoRestriction`	`geoRestrictions`

Media Limits

Kavenio validates supplied media metadata before calling Meta:

Media	Limit
Feed images	Up to 10 images, JPEG/PNG/GIF, 4 MB each
Feed videos	MP4/MOV, 1 second to 240 minutes, 4 GB
Reels	One MP4/MOV video, 3 to 90 seconds, 9:16, at least 540x960, 24-60 FPS, 4 GB
Story images	One JPEG/PNG image, 10 MB
Story videos	One MP4/MOV video, 3 to 90 seconds, 9:16, at least 540x960, 24-60 FPS, 4 GB
Geo restrictions	Up to 25 uppercase country codes

Meta can still reject media after fetching the URL if the actual file does not match the metadata or current Page API constraints.

Unsupported Cases

Kavenio does not support these Facebook actions through post publishing:

Story captions or Story first comments
Story provider-native drafts or native scheduling
Reel links
native edit or unpublish after publication

Common Errors

Error	Meaning	Fix
`Facebook feed posts can include at most 10 images.`	Too many feed images.	Send at most 10 images.
`Facebook Reel publishing requires exactly one video media item.`	Reel media is missing or invalid.	Send one video media item.
`Facebook Story publishing does not support captions.`	Story `content` is not empty.	Omit story caption text.
`Facebook advanced Story options are not implemented in this slice.`	A Story-only unsupported option was supplied.	Remove first comments, links, geo restrictions, and native scheduling fields from Story targets.
`Connected Facebook credential does not include pages_manage_engagement required for first comments.`	The saved connection predates or lost comment permission.	Reconnect Facebook or omit `firstComment`.

​Quick Reference

​Create A Feed Post

​Reels

​Stories

​Carousel Feed Posts

​Provider-Native Drafts And Scheduling

​Platform-Specific Fields

​Media Limits

​Unsupported Cases

​Common Errors