Facebook

Overview

The facebook platform publishes to Facebook Pages (not personal profiles). Every Page you grant during login becomes its own account in Relaycast. You can post:

• Text posts, optionally with a link preview card
• 1–10 photos
• 1 video (with optional title and custom thumbnail)
• Reels (one vertical video)
• Stories (one photo or one video)
• Unpublished Page posts (for ads, or to publish later in Meta Business Suite)

Connect the account

In Integrations, choose Facebook, log in, and select the Pages to connect.

App setup (self-hosted)

1. Create a Meta app with the use case Manage everything on your Page (this adds Facebook Login).
2. Add https://social-publish-kappa.vercel.app/api/integrations/facebook/callback to Facebook Login → Settings → Valid OAuth Redirect URIs (override with FACEBOOK_REDIRECT_URI).
3. Set FACEBOOK_APP_ID and FACEBOOK_APP_SECRET. Optionally pin the Graph API version with META_GRAPH_VERSION.

Always requested: pages_show_list, pages_read_engagement, pages_manage_posts. Optional features request extra permissions only when their flag is set, because Meta rejects the whole login ("Invalid Scopes") when a requested permission isn't added to the app:

Page tokens obtained this way don't expire. If one is invalidated (password change, app removed, Page role removed), the next publish marks the account reconnect_required.

Post types & media rules

Choose the post type with options.publishAs:

Reel and Story duration and aspect ratio are checked by Facebook during processing, not before the post is queued.

Options

Examples

Link post

curl -X POST https://social-publish-api.onrender.com/v1/posts \
  -H "x-access-key: $RELAYCAST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "content": "Our 2026 product report is out.",
    "targets": [{
      "accountId": "9b2e4c61-3f7a-4d8e-b5c2-1a0f9e8d7c6b",
      "options": { "publishAs": "feed", "link": "https://example.com/report-2026" }
    }],
    "publishNow": true
  }'

const res = await fetch("https://social-publish-api.onrender.com/v1/posts", {
  method: "POST",
  headers: {
    "x-access-key": process.env.RELAYCAST_API_KEY!,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    content: "Our 2026 product report is out.",
    targets: [
      {
        accountId: "9b2e4c61-3f7a-4d8e-b5c2-1a0f9e8d7c6b",
        options: { publishAs: "feed", link: "https://example.com/report-2026" },
      },
    ],
    publishNow: true,
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://social-publish-api.onrender.com/v1/posts",
    headers={"x-access-key": os.environ["RELAYCAST_API_KEY"]},
    json={
        "content": "Our 2026 product report is out.",
        "targets": [{
            "accountId": "9b2e4c61-3f7a-4d8e-b5c2-1a0f9e8d7c6b",
            "options": {"publishAs": "feed", "link": "https://example.com/report-2026"},
        }],
        "publishNow": True,
    },
)
data = res.json()["data"]

Reel with title and thumbnail

{
  "content": "60 seconds with our design team",
  "media": [{ "url": "https://cdn.example.com/design-team.mp4", "type": "video" }],
  "targets": [{
    "accountId": "9b2e4c61-3f7a-4d8e-b5c2-1a0f9e8d7c6b",
    "options": {
      "publishAs": "reel",
      "title": "Meet the design team",
      "thumbnail": "https://cdn.example.com/design-team-cover.jpg"
    }
  }],
  "scheduledFor": "2026-11-05T12:00:00Z"
}

Unpublished photo post

{
  "content": "Holiday sale creative",
  "media": [{ "url": "https://cdn.example.com/sale.jpg", "type": "image" }],
  "targets": [{
    "accountId": "9b2e4c61-3f7a-4d8e-b5c2-1a0f9e8d7c6b",
    "options": { "publishImmediately": false }
  }],
  "publishNow": true
}

Analytics & comments

• Analytics: reactions (likes), comments and shares for every post. Impressions, views and clicks (and video/Reel play counts) come from Page insights and need FACEBOOK_ENABLE_INSIGHTS=true plus a reconnect.
• Inbox: Messenger conversations for the Page, with FACEBOOK_ENABLE_INBOX=true. Meta only allows replies within 24 hours of the person's last message. See Inbox & Comment Automation.
• Comment automations are not available for Facebook.

Limitations & common errors