Facebook API

Postproxy publishes feed posts, Reels, and Stories to a Facebook Page, and offers the fullest engagement support of any network: complete comment management (including likes) and Messenger direct messages with reactions and private replies.

Every request below uses the base URL https://api.postproxy.dev and an Authorization: Bearer YOUR_API_KEY header. Replace YOUR_API_KEY and the example IDs with your own.

At a glance


Platform ID	`facebook`
Formats	`post` (default), `reel`, `story`
Character limit	63,206 (2,200 for Reels)
Media	Optional on feed posts; required for Reels and Stories
Placements	Pages — `page_id` (required)
Comments	List, reply, delete, hide/unhide, like/unlike
Direct messages	Yes — text, media, reactions, private replies
Post chains	No

Publishing

Formats

Format	Description
`post`	Feed post (default)
`reel`	Facebook Reel
`story`	Facebook Story

Every format requires a page_id — the Page to publish to. Fetch the IDs from placements.

Feed post

Parameter	Type	Required	Description
`format`	string	No	`"post"` (default)
`first_comment`	string	No	Comment added after publishing
`page_id`	string	Yes	Page to publish to — fetch from placements

Media	Max size	Formats	Count	Duration
Image	10 MB	jpg, png, gif, webp	10	—
Video	4 GB	mp4, mov	1	1 s – 4 h

Text-only posts are allowed; media is optional.
Images and video cannot be mixed.
Minimum image dimensions: 200×200 px.

# Feed post with an image and a first comment
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "Exciting news! Check out our latest update." },
       "profiles": ["prof_abc123"],
       "media": ["https://example.com/image.jpg"],
       "platforms": {
         "facebook": {
           "format": "post",
           "first_comment": "What do you think? Let us know!",
           "page_id": "123456789"
         }
       }
     }'

Reel

Parameter	Type	Required	Description
`format`	string	Yes	`"reel"`
`title`	string	No	Title of the Reel
`page_id`	string	Yes	Page to publish to — fetch from placements

Media	Max size	Formats	Count	Duration
Video	300 MB	mp4, mov	1	3 s – 60 s

A video is required. Reels do not support a first comment.

# Reel
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "Behind the scenes 🎬" },
       "profiles": ["prof_abc123"],
       "media": ["https://example.com/video.mp4"],
       "platforms": {
         "facebook": { "format": "reel", "title": "Launch BTS", "page_id": "123456789" }
       }
     }'

Story

Parameter	Type	Required	Description
`format`	string	Yes	`"story"`
`page_id`	string	Yes	Page to publish to — fetch from placements

Media	Max size	Formats	Count	Duration
Image	10 MB	jpg, png	1	—
Video	4 GB	mp4, mov	1	3 s – 60 s

Media is required; text captions are not supported.
Minimum dimensions: 500×500 px.

# Story (single image)
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": {},
       "profiles": ["prof_abc123"],
       "media": ["https://example.com/story.jpg"],
       "platforms": { "facebook": { "format": "story", "page_id": "123456789" } }
     }'

Placements

A Facebook profile can manage several Pages. List them with the placements endpoint — each placement’s id is the page_id you pass when creating a post.

page_id is required on every post — there is no default Page, even when the profile has only one. Pass the id of the Page you want to publish to.

# List the Pages (placements) for a Facebook profile
curl "https://api.postproxy.dev/api/profiles/prof_abc123/placements" \
     -H "Authorization: Bearer YOUR_API_KEY"

Comments

Facebook has the most complete Comments API support. All comment writes are asynchronous and need the profile_id query parameter.

Action	Supported
List / read	Yes
Reply	Yes
Delete	Yes
Hide / unhide	Yes
Like / unlike	Yes

Comment attachments can carry photo, video, sticker, and share media.
Author metadata is available when Facebook returns it: is_verified_user, is_user_follow_business, is_business_follow_user, and follower_count.

# List comments on a post
curl "https://api.postproxy.dev/api/posts/post_abc123/comments?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Reply to a comment (omit parent_id to comment on the post itself)
curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "body": "Appreciate the feedback!", "parent_id": "cmt_abc123" }'

# Like / unlike a comment
curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/like?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/unlike?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Hide / unhide a comment
curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/hide?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/unhide?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Delete a comment
curl -X DELETE "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

Direct messages

Facebook Messenger is supported through the Direct Messages API. Each send accepts either text or a single attachment.

Capability	Supported
Send / receive text	Yes
Attachments	Yes — one per send
Reactions	Yes — named reactions map to emoji (`love` → ❤, `like` → 👍, …)
Edit outbound message	No
Delivery / read receipts	Yes
Private reply to a comment	Yes
Inbound delivery	Webhook

24-hour window. Free-form messages are only allowed within 24 hours of the participant’s last message. Sending outside the window is not supported.
Private replies DM a commenter directly, bypass the 24-hour window (up to 7 days), and are allowed once per comment.
Start a chat with the participant’s Page-scoped ID (PSID) as participant_external_id.

# Create or find a chat by PSID
curl -X POST "https://api.postproxy.dev/api/profiles/prof_abc123/chats" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "participant_external_id": "7000000000000000", "participant_name": "Jane Doe" }'

# Send a text message
curl -X POST "https://api.postproxy.dev/api/chats/chat_abc123/messages" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "body": "Hi! How can we help?" }'

# Send a single media attachment
curl -X POST "https://api.postproxy.dev/api/chats/chat_abc123/messages" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "media": ["https://example.com/receipt.pdf"] }'

# React to a message (named reaction -> emoji)
curl -X POST "https://api.postproxy.dev/api/messages/msg_abc123/react" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "reaction": "like" }'

# Private reply to a commenter (bypasses the 24h window, once per comment)
curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/private_reply?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "text": "Sent you a DM with the details!" }'

Webhooks

Subscribe with the Webhooks API. Create a subscription:

curl -X POST "https://api.postproxy.dev/api/webhooks" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/webhooks/postproxy",
       "events": ["platform_post.published", "comment.created", "message.received", "reaction.received"]
     }'

Events relevant to Facebook:

Event	When
`post.processed`	A post is ready to publish
`platform_post.published`	A post was published to the platform
`platform_post.failed`	A post failed to publish (retries exhausted)
`platform_post.failed_waiting_for_retry`	A publish attempt failed; will retry
`platform_post.insights`	New analytics snapshot
`comment.created`	A comment was synced on a Facebook post
`message.received` / `.sent`	Inbound / outbound DM
`message.delivered` / `.read`	Delivery and read receipts
`message.edited`	An inbound message was edited
`reaction.received`	A reaction was added or removed on a message
`profile.connected` / `.disconnected`	Connection state changed
`profile.stats`	New profile stats snapshot (once per Page)
`media.failed`	A media attachment failed to process

Facebook does not report message deletions — message.deleted only fires for Instagram.

Notes

Publishing targets a Facebook Page, not a personal profile.
page_id is required on every post; fetch it from placements.
Reels are video-only and capped at 60 seconds; Stories require 500×500 px media.