Facebook API

Schedule and automate Facebook Page posts with RelayAPI — feed posts, multi-image, stories, reels, and first comments.

Quick Reference

Before You Start

Quick Start

Post to a Facebook Page:

import Relay from '@relayapi/sdk';

const client = new Relay();

const post = await client.posts.create({
  content: 'Exciting news from our Page!',
  targets: ['facebook'],
  scheduled_at: 'now'
});

console.log(post.id); // post_abc123

Content Types

Text-Only Post

Facebook is one of few platforms that supports text-only posts. First ~480 characters are visible before the "See more" fold.

const post = await client.posts.create({
  content: 'Just a text update for our followers.',
  targets: ['facebook'],
  scheduled_at: 'now'
});

Single Image Post

const post = await client.posts.create({
  content: 'Check out this photo!',
  targets: ['facebook'],
  media: [
    { url: 'https://cdn.example.com/photo.jpg', type: 'image' }
  ],
  scheduled_at: 'now'
});

Multi-Image Post (Up to 10)

Up to 10 images per post. Cannot mix images and videos in the same post.

const post = await client.posts.create({
  content: 'Photo dump from our event!',
  targets: ['facebook'],
  media: [
    { url: 'https://cdn.example.com/photo1.jpg', type: 'image' },
    { url: 'https://cdn.example.com/photo2.jpg', type: 'image' },
    { url: 'https://cdn.example.com/photo3.jpg', type: 'image' }
  ],
  scheduled_at: 'now'
});

Video Post

Single video per post. Up to 4 GB, max 240 minutes for feed videos.

const post = await client.posts.create({
  content: 'Watch our latest video!',
  targets: ['facebook'],
  media: [
    { url: 'https://cdn.example.com/video.mp4', type: 'video' }
  ],
  scheduled_at: 'now'
});

Story

Media is required for stories. Text captions are not displayed on Facebook Stories. Interactive stickers are not available via the API.

const post = await client.posts.create({
  targets: ['facebook'],
  media: [
    { url: 'https://cdn.example.com/story.jpg', type: 'image' }
  ],
  scheduled_at: 'now',
  target_options: {
    facebook: {
      content_type: 'story'
    }
  }
});

Reel

Single vertical video, 3-60 seconds. Reels support a separate title field.

const post = await client.posts.create({
  content: 'Behind the scenes of our latest shoot',
  targets: ['facebook'],
  media: [
    { url: 'https://cdn.example.com/reel.mp4', type: 'video' }
  ],
  scheduled_at: 'now',
  target_options: {
    facebook: {
      content_type: 'reel',
      title: 'Studio day'
    }
  }
});

Post with First Comment

Automatically post a first comment after publishing. Useful for adding links without suppressing reach.

const post = await client.posts.create({
  content: 'New product launch!',
  targets: ['facebook'],
  media: [
    { url: 'https://cdn.example.com/product.jpg', type: 'image' }
  ],
  scheduled_at: 'now',
  target_options: {
    facebook: {
      first_comment: 'Link to purchase: https://shop.example.com'
    }
  }
});

Multi-Page Posting

Post to multiple Facebook Pages in a single request by targeting different account IDs.

const post = await client.posts.create({
  content: 'News from all our brands!',
  targets: ['acc_fb_brand1', 'acc_fb_brand2'],
  scheduled_at: 'now'
});

Media Requirements

Images

Videos

target_options Fields

All fields go inside target_options.facebook on your post request.

await client.posts.create({
  content: 'A local preview before launch',
  targets: ['facebook'],
  scheduled_at: 'now',
  target_options: {
    facebook: {
      published: false,
      place_id: '123456789012345',
      targeting: {
        geo_locations: { countries: ['GB'] },
        age_min: 18,
      },
      feed_targeting: {
        geo_locations: { cities: [{ key: '2420605', radius: 20, distance_unit: 'mile' }] },
      },
    },
  },
});

Facebook colored/background posts are not exposed: RelayAPI has no verified official Page-create contract for that field and rejects rather than guessing.

Common Errors

Known Quirks

• Pages only — you cannot post to personal Facebook profiles via the API.
• Cannot mix images and videos in the same post.
• WebP images are auto-converted to JPEG by Facebook.
• Story text captions are not displayed — only the media is shown.
• Story interactive stickers are not available via the API.
• Facebook often rejects images over 4 MB in practice, even though the documented limit is higher.
• Tokens expire frequently — subscribe to the account.disconnected webhook to detect token expirations.
• GIFs should use type: "video" — they auto-play and loop when sent as video type.
• First ~480 characters visible before the "See more" fold on feed posts.

Published edits and social actions

RelayAPI can edit published Page post text and owned comments, hide/unhide comments, like/unlike posts, and send Messenger read receipts for persisted inbound messages. These provider writes require durable idempotency and the appropriate pages_manage_posts, pages_manage_engagement, or pages_messaging grant. See Published Edits and Social Actions.

Automations

Facebook Messenger is a Tier 1 automation platform — full inbound conversational event coverage and 9 outbound send node types.

Triggers

Send nodes

All messaging nodes hit POST {GRAPH_BASE.facebook}/{page-id}/messages. Comment operations use the Graph API comment endpoints.