# OmniSocials Facebook API > Publish posts, photos, links, Stories and Reels to your Page. Answer Messenger and comments, and read insights. One API key, on OmniSocials’ approved Meta app. This is the machine-readable version of [omnisocials.com/facebook-api](https://omnisocials.com/facebook-api), maintained for AI agents. Facts checked against the OmniSocials app and API on October 17, 2026. Platform reference: [docs.omnisocials.com/platforms/facebook](https://docs.omnisocials.com/platforms/facebook). API reference: [docs.omnisocials.com/api](https://docs.omnisocials.com/api). ## Basics - Base URL: `https://api.omnisocials.com/v1` - Auth: `Authorization: Bearer omsk_live_...`. One key belongs to one workspace. Keys are created in the app under Settings, API. - Channel id in `accounts`: `facebook`. The account connects inside the OmniSocials app, not through the API. - Rate limit: 100 requests per minute per key. A 429 carries `Retry-After`. - Responses use a `{ "data": ... }` envelope. Create returns `201`. - Webhooks: `post.scheduled`, `post.published`, `post.failed`, `post.approved`, `post.rejected`, signed with HMAC-SHA256 in `X-OmniSocials-Signature`. ## Skip the Meta app review Facebook's own API needs a Meta app, nine permissions through App Review, Page tokens and a three-step video upload. OmniSocials already did that work. - On your own: Meta app, App review, Verification, Hosting, Page tokens, Uploads, Polling, Retries, then the first post. - Permissions your own app must get approved: `pages_show_list`, `pages_read_engagement`, `pages_manage_posts`, `pages_manage_metadata`, `pages_manage_engagement`, `pages_messaging`, `read_insights`, `publish_video`, `business_management`. - On OmniSocials: sign in, create an API key, POST. All 9 permissions already approved. ## Schedule a post ```bash curl -X POST https://api.omnisocials.com/v1/posts/create \ -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "reel", "content": "Post from your own code: SDKs in 8 languages.", "accounts": ["facebook"], "media_urls": ["https://cdn.example.com/sdks.mp4"], "schedule_at": "2026-10-22T18:00:00Z", "facebook": { "first_comment": "Which SDK do you use?", "thumbnail_type": "from-video", "thumb_offset": 3000 } }' ``` The answer (`201`, shortened): ```json { "data": { "id": "1024", "status": "scheduled", "app_url": "https://app.omnisocials.com/create-post/1024" } } ``` ## Every format, one request Posts with photos or a video, link posts, Stories and Reels share one request shape. Set the type, add media URLs or a link and a time. OmniSocials checks the media against Facebook’s rules before it uploads. - **Posts and photos.** Text with one photo, several photos or one video, and a first comment right after the post goes live. (`media_urls`, `facebook.first_comment`) - **Link posts.** Send a link without media. Facebook builds the preview card from the linked page’s own tags. (`link_url`) - **Stories and Reels.** Stories go out slide by slide, up to 10, without a caption. Reels take a frame or an image as the thumbnail. (`type: "story"`, `type: "reel"`, `thumbnail_type`) ### Post ```json { "content": "The Social Inbox has an API now. Four new endpoints for comments, DMs and mentions.", "accounts": ["facebook"], "media_urls": ["https://cdn.example.com/inbox-api.jpg"], "schedule_at": "2026-10-20T09:00:00Z", "facebook": { "first_comment": "The docs: docs.omnisocials.com/api" } } ``` ### Photos ```json { "content": "Best times to post, worked out from your own posts. Here is how it works.", "accounts": ["facebook"], "media_urls": [ "https://cdn.example.com/best-times-1.jpg", "https://cdn.example.com/best-times-2.jpg" ], "schedule_at": "2026-10-24T09:00:00Z", "facebook": { "first_comment": "Which day works best for your Page?" } } ``` ### Link ```json { "content": "Everything we shipped this month, in one place: https://omnisocials.com/changelog", "accounts": ["facebook"], "link_url": "https://omnisocials.com/changelog", "schedule_at": "2026-10-23T12:00:00Z" } ``` ### Story ```json { "type": "story", "content": "New this week", "accounts": ["facebook"], "media_urls": [ "https://cdn.example.com/bluesky.jpg", "https://cdn.example.com/mastodon.jpg" ], "schedule_at": "2026-10-21T09:00:00Z" } ``` ### Reel ```json { "type": "reel", "content": "Post from your own code: SDKs in 8 languages.", "accounts": ["facebook"], "media_urls": ["https://cdn.example.com/sdks.mp4"], "schedule_at": "2026-10-22T18:00:00Z", "facebook": { "first_comment": "Which SDK do you use?", "thumbnail_type": "from-video", "thumb_offset": 3000 } } ``` ## Connect a Page once, post from code Sign in with Facebook once inside OmniSocials and pick the Page. Create an API key, and your code posts, replies and reports for that Page. - **Facebook Login.** Sign in with Facebook once and pick the Page. Pages you manage; personal profiles and Groups can’t connect. - **A key per workspace.** A key only reaches its own workspace. Inbox access is switched on per key. - **What the Page can post.** The accounts call lists the connected Page with the formats it takes. (`GET /v1/accounts`, `content_types`) `GET /v1/accounts?platform=facebook` answers: ```json { "data": [ { "id": "4127_facebook", "platform": "facebook", "display_name": "OmniSocials", "content_types": ["post", "story", "reel"], "status": "active" } ], "workspace_name": "OmniSocials" } ``` ## Answer Messenger and comments List the Page’s Messenger conversations, comments and mentions, then reply, hide or delete from your own code. The API checks Meta’s 24-hour window before it sends a DM. - **Comments.** Reply under the comment, hide it or delete it. Each comment comes with the post it sits on. (`/inbox/messages/:id/hide`) - **Messenger.** Answer within Meta’s 24-hour window. Outside it the API says so with outside_messaging_window, before anything is sent. (`/conversations/:id/reply`) - **Mentions.** Posts and comments that mention your Page show up in the same list. A reply goes under the post. (`type=mention`) `GET /v1/inbox/conversations?platform=facebook&type=dm` lists the conversations. Reply with `POST /v1/inbox/conversations/8812/reply`: ```json { "text": "Yes. Send a video URL with type reel." } ``` ## Read what Facebook reports Views, reactions by type, comments, shares and clicks per post, video views and watch time, and the Page’s followers per day. The API returns the same numbers the app charts. - **Per post and per Reel.** Views, reactions by type, comments, shares, clicks and link clicks. Videos add views and watch time, Reels replays and follows. (`/analytics/posts/:id`) - **Per Page and workspace.** A daily snapshot of the Page: followers, new and lost followers, views and profile views. Plus a workspace overview. (`/analytics/accounts`, `/analytics/overview`) - **Best times to post.** Days and hours worked out from your own Facebook history, once 15 of your posts are analyzed. (`/analytics/best-times`) `GET /v1/analytics/posts/1019` answers: ```json { "data": { "post_id": "1019", "platforms": { "facebook": { "metrics": { "views": 3412, "clicks": 238, "link_clicks": 64, "likes": 141, "total_reactions": 186, "reactions": { "like": 141, "love": 32, "wow": 9, "haha": 4 }, "comments": 27, "shares": 19 } } } } } ``` ## Facebook’s rules, in one place OmniSocials checks every post against them before it reaches Meta, so a bad file fails in your request, not at publish time. | Limit | Value | | --- | --- | | Caption | 63,206 characters, a post needs text | | First comment | 8,000 characters, not on Stories | | Photos | JPEG, PNG, GIF or WebP, up to 10 MB each | | Media | Photos or one video per post, not both | | Story | Up to 10 slides, 60 seconds per video | | Video | MP4 or MOV, 100 MB in media_urls, 1 GB via upload-from-url | | Messenger reply | Within 24 hours of the last message | | Replies | 1,000 a day per workspace | | Rate limit | 100 requests a minute per API key | | Accounts | Facebook Pages, one per workspace | ## Your first Reel in three steps About five minutes from sign-up to a scheduled Reel on your Page. Then hand the key to your coding agent. 1. **Create an API key** (`Settings › API`). Start your trial, open Settings, API and create a key. It is shown once. 2. **Connect your Page** (`GET /v1/accounts`). Sign in with Facebook in OmniSocials once and pick the Page. Then list it from your code. 3. **Send your first Reel** (`POST /v1/posts/create`). Post now with create-and-publish, or add schedule_at to plan it. ## FAQ ### Do I need my own Meta app or an app review? No. The Page connects through OmniSocials’ approved Meta app, with Facebook’s own sign-in. You call the OmniSocials API with an API key and never handle Page tokens. ### Which Facebook accounts can I post to? Facebook Pages you manage. Personal profiles and Groups can’t be connected. Each workspace connects one Page; a second Page goes in a second workspace with its own key. ### Can my own users connect their Facebook Pages through the API? Not yet. Pages connect inside the OmniSocials app. Every API key in that workspace can then post to the Page. ### Can I schedule Facebook posts through the API? Yes. Send schedule_at with the request and OmniSocials keeps the queue and publishes on time, with a webhook when it is live. ### Which formats can I publish? Text posts, posts with photos or one video, link posts (Facebook builds the preview card from the page you link), Stories of up to 10 photos or videos and Reels. A post takes photos or a video, not both. Stories go out without a caption. ### Can I add a first comment or a Reel thumbnail? Yes. In the facebook object, set first_comment for posts and Reels. For a Reel or video, set thumbnail_type to from-video with thumb_offset in milliseconds, or to from-library with cover_url. ### Can I read and answer Messenger messages and comments? Yes. The inbox endpoints list the Page’s Messenger conversations, comments and mentions, reply to them, and hide or delete comments. DM replies follow Meta’s 24-hour window: outside it the API answers 422 outside_messaging_window. The API cannot start a new conversation. ### Can I post to my Page and Instagram in one request? Yes. Put both accounts in accounts. content takes one text for both or a text per platform, and the facebook and instagram objects carry each platform’s own options, such as the first comment or the Reel’s cover. ### What happens when a Facebook post fails to publish? OmniSocials retries it up to 3 times, 15 minutes apart. Before a feed post or video is sent again, it checks whether the first attempt already went live, so the post never shows up twice. Then post.published or post.failed fires. ### Can the API send a DM when someone comments? Not on Facebook yet. Comment-to-DM automations work on Instagram today, and Facebook Pages are on the roadmap. ### How do webhooks work? Register a URL and pick the events: post.scheduled, post.published, post.failed, post.approved and post.rejected. Every delivery is signed with HMAC-SHA256 in the X-OmniSocials-Signature header. ### What are the rate limits? 100 requests per minute per API key, and 1,000 inbox replies a day per workspace. The SDKs retry automatically and respect the Retry-After header. ### Is the Facebook Graph API free? Meta doesn’t charge for the Graph API, but publishing to Pages needs a Meta app with its permissions approved in App Review. Through OmniSocials you post on its approved Meta app, and the API is part of the plan, $10 per seat per month billed annually. ### How much does OmniSocials cost? One plan with every feature included: $10 per seat per month billed annually, or $12 billed monthly. Team members and client seats cost the same. Every account starts with a 14-day free trial. The REST API, the SDKs, the CLI, webhooks and the MCP server are part of that one plan. ## Pricing From $10 per seat a month, API included. 14-day free trial. ## Related - [Facebook scheduler](https://omnisocials.com/facebook.md) - [Facebook MCP server](https://omnisocials.com/facebook-mcp.md) - [All channels](https://omnisocials.com/channels.md) - [Facebook character limits](https://omnisocials.com/facebook-character-limits) - [Facebook video lengths](https://omnisocials.com/facebook-video-lengths) ## Links - Page: https://omnisocials.com/facebook-api - Facebook platform docs: https://docs.omnisocials.com/platforms/facebook - API reference: https://docs.omnisocials.com/api - REST API overview: https://omnisocials.com/api.md - MCP server: https://omnisocials.com/mcp.md - Sign up: https://app.omnisocials.com/signup