Facebook

Publish posts, photos, videos, and link previews to Facebook Pages via the PostPeer API.

Overview

Publish text, images, videos, and link-preview posts to Facebook Pages via the Graph API. PostPeer handles OAuth, the long-lived token exchange, and the per-Page token model that Meta uses.

Pages only. Posting to personal Facebook profiles via the Graph API was deprecated by Meta years ago and is unavailable to most apps. If you need to post to a personal account, you'll have to do it manually in the Facebook UI.

Quick Start

1. Connect Facebook Pages

curl https://api.postpeer.dev/v1/connect/facebook \
  -H "x-access-key: YOUR_API_KEY"

Response:

{
  "url": "https://www.facebook.com/v23.0/dialog/oauth?..."
}

Redirect the user to that URL. On Meta's consent screen they pick which Pages they want to grant access to. After they confirm, PostPeer's callback creates one integration per Page.

2. Find your account IDs

A user with three Pages will have three integrations after connecting once. List them:

curl "https://api.postpeer.dev/v1/connect/integrations?platform=facebook" \
  -H "x-access-key: YOUR_API_KEY"

Each entry has:

{
  "id": "abc123",
  "platform": "facebook",
  "platformUserId": "104251038...",
  "displayName": "Acme Co",
  "imageUrl": "https://assets.postpeer.dev/...",
  "createdAt": "..."
}

The id is what you pass as accountId on a post. You'd typically pair this with profiles so you can group all of an end-user's Pages together.

3. Publish a post

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New product drop today.",
    "platforms": [
      { "platform": "facebook", "accountId": "abc123" }
    ],
    "publishNow": true
  }'

Response:

{
  "success": true,
  "status": "published",
  "platforms": [
    {
      "platform": "facebook",
      "success": true,
      "platformPostId": "104251038_998877665",
      "platformPostUrl": "https://www.facebook.com/104251038/posts/998877665"
    }
  ]
}

Features

Text-only posts

Just content. Goes straight to the Page's feed.

Link preview posts

Pass a URL via platformSpecificData.link and Facebook auto-fetches that URL's Open Graph metadata to render a preview card.

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Read our latest case study:",
    "platforms": [
      {
        "platform": "facebook",
        "accountId": "abc123",
        "platformSpecificData": {
          "link": "https://yourapp.com/case-studies/acme"
        }
      }
    ],
    "publishNow": true
  }'

Single image

Attach one image mediaItem. The content becomes the photo caption.

{
  "content": "Behind the scenes today",
  "platforms": [{ "platform": "facebook", "accountId": "abc123" }],
  "mediaItems": [
    { "type": "image", "url": "https://cdn.example.com/photo.jpg" }
  ]
}

Photo carousel (up to 10 images)

Attach 2–10 image mediaItems. PostPeer uploads each as unpublished, then creates a single feed post that bundles them all.

{
  "content": "Recap of yesterday's launch event",
  "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" }
  ]
}

Video

Attach one video mediaItem. PostPeer asks Facebook's servers to fetch the URL directly — works for hosted MP4s up to a few hundred MB. The content becomes the video description.

{
  "content": "Quick walkthrough of the new dashboard",
  "platforms": [{ "platform": "facebook", "accountId": "abc123" }],
  "mediaItems": [
    { "type": "video", "url": "https://cdn.example.com/walkthrough.mp4" }
  ]
}

Reels and Stories are separate Meta APIs and are not currently supported.

Draft / unpublished mode

Pass published: false in platformSpecificData to create the post in draft state. Useful for staging or for letting your end-user finalize the post inside Facebook's own composer.

{
  "platformSpecificData": { "published": false }
}

Limits

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

Tokens & reconnection

Page access tokens that PostPeer stores are derived from a long-lived user token, which makes them non-expiring under normal use. You typically only need to reconnect when:

The user revokes the app from their Facebook Settings
The user changes their Facebook password
The user removes the integration on PostPeer's side and reconnects

If a posting call returns an authentication error, that's the signal — surface a "reconnect Facebook" prompt and have the user go through /v1/connect/facebook again.

On this page