Facebook API - SocialAPI

The Facebook API in SocialAPI connects Facebook Pages. It publishes text, link, photo, video, album, Reel, and Story posts, reads and moderates comments, sends private replies and Messenger direct messages (DMs), and reads mentions. SocialAPI’s own Meta app connects the Pages, so you register nothing: see Platform apps. A Facebook profile is not supported: only Pages.

At a glance

Field	Value
Platform slug	`facebook`
Auth	OAuth 2.0 (Meta), one login for every Page the person manages
Platform API	Meta Graph API (Facebook Pages and Messenger)
Status	Available

Capabilities

An unsupported call returns 501 resource.not_supported.

Feature	Status	Condition
Publish text, link, photo, video, multi-photo album, Reel, Story	Yes	See Facebook publishing
Schedule a post	Yes	`scheduled_at` on the post
First comment on a post	Yes	Not on a Story
Update a published post	No	`PATCH /v1/posts/{pid}` returns `409 post.state_invalid` for a published post. A `draft`, `scheduled`, or `failed` post can be edited before it publishes. To correct it, delete the post with `DELETE /v1/posts/{pid}` and publish a new one
Delete a published post	Yes
List posts	Yes	Posts in the Page feed. List posts does not return a Reel, even when `share_to_feed` is `true`
List comments and replies	Yes	Comments are read per post
Reply to a comment	Yes
Hide, unhide, delete a comment	Yes
Like or unlike a comment	Yes	The Page likes the comment
Private reply to a comment	Yes	One per comment, within 7 days of the comment
DMs: list, read, send	Yes	Inside the 24-hour messaging window. Text and attachments. A send ignores `quick_replies`, `buttons`, and `cards`
React to a DM	Yes
Mentions	Partial	`GET /v1/accounts/{id}/mentions` returns posts that tag the Page. A mention in a comment arrives as a `mention.received` event
Reply to a mention	Yes	A public comment on the mention
Reviews	No	SocialAPI does not read Facebook reviews: Meta deprecated Page recommendations in Graph API v22.0. `GET /v1/inbox/reviews/{account_id}` returns `422 account.platform_unsupported`
Automations	Yes	Comment and DM triggers, buttons on the first private reply, multi-step flows. A `send_dm` action delivers no buttons. No `follows_account` filter and no Follow gate: `400 validation.filter_unsupported`
Analytics	Yes	See Analytics
Page insights	Yes	`GET /v1/platforms/facebook/accounts/{id}/summary` (trailing 30 days) and `GET /v1/platforms/facebook/accounts/{id}/insights/daily`. Needs `read_insights`: see Page insights
Webhook events	Yes	See Webhook events

The cross-platform matrix is on Platforms.

Connect an account

Connect with POST /v1/accounts/connect and "platform": "facebook". The shared flow, request fields, and result are in Connect accounts, and the redirect parameters are in Redirect parameters.

curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "facebook",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "state": "session_abc123"
  }'

Response (HTTP 202):

{
  "auth_url": "https://www.facebook.com/v25.0/dialog/oauth?client_id=...&state=...",
  "state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2",
  "message": "Open this link to connect your facebook account. Once you've authorized, the account will be connected automatically."
}

After the person authorizes, the redirect carries status=success and the brand’s Facebook account. That account holds every Page the login granted that none of your other brands already holds. A Page that another of your brands holds stays with that brand.

A login that grants no Page ends with status=error and error=platform.facebook.no_pages on your redirect_uri.
A login whose every Page belongs to another of your brands ends with status=error and error=platform.facebook.no_assignable_pages.
A brand whose Facebook account is connected through a different login ends with status=error and error=account.different_login. Disconnect the brand’s Facebook account first.
Reconnecting the same login refreshes the access for every brand that uses it, not only the brand you reconnected from.

Pages of an account

List the Pages of a connected account with GET /v1/accounts/{id}/pages. Each Page has at least an id (sapi_page_ prefix), platform_page_id, name, is_default, and is_active. A Page also carries profile_picture_url, category, followers_count, username, link, verification_status, cover_photo_url, about, and enriched_at, each omitted when it has no value. Publish to a Page with page_id on the post target: see Delivery. PATCH /v1/accounts/{id}/pages/{pageId} sets is_default or is_active. A Facebook login is a shared credential. One login can serve many brands, and each Page belongs to exactly one brand. List the Pages a login can manage, live from Facebook, with the brand that holds each:

curl "https://api.social-api.ai/v1/platforms/facebook/logins/cred_01J8X3Q4R5M6N7P8V2K0W1J/pages" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "login_id": "cred_01J8X3Q4R5M6N7P8V2K0W1J",
  "pages": [
    {
      "platform_page_id": "104857392011223",
      "name": "Acme Bakery",
      "assignable": true
    }
  ],
  "count": 1
}

Field	Description
`login_id`	The login you asked about
`pages[].platform_page_id`, `name`	Facebook’s Page ID and the Page’s name
`pages[].picture_url`, `category`	The Page’s picture and category. Each is omitted when Facebook returns none
`pages[].assignable`	`true` when no brand holds the Page. `false` when a brand holds it: `assigned_brand_id`, `assigned_brand_name`, and `assigned_account_id` then name it
`count`	The number of Pages in `pages`

login_id is on each connected account. Move a Page to a brand with POST /v1/platforms/facebook/logins/{loginId}/pages/{pageId}/assign. A Page that another of your brands holds moves to the target brand. The call needs the accounts:manage scope.

curl -X POST "https://api.social-api.ai/v1/platforms/facebook/logins/cred_01J8X3Q4R5M6N7P8V2K0W1J/pages/104857392011223/assign" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "7d2e4b1a-9c3f-4e5d-8a6b-1f2e3d4c5b6a"}'

Response (HTTP 201):

{
  "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "brand_id": "7d2e4b1a-9c3f-4e5d-8a6b-1f2e3d4c5b6a",
  "platform_page_id": "104857392011223"
}

HTTP	Code	When it occurs
400	`validation.field_required`	The body has no `brand_id`
400	`validation.page_not_granted`	The Page is not accessible through this login
404	`resource.not_found`	The login does not exist
404	`brand.not_found`	The brand does not exist or your key cannot reach it
409	`account.different_login`	The brand’s Facebook account uses a different login

Comments

List comments on a post with GET /v1/inbox/comments/{postId}, where postId is the post’s platform ID. Reply, hide, unhide, delete, like, and unlike work as described in Comments.

Edited comments. Facebook sends an edited comment again, as another comment.received event. Automations ignore edits and answer new comments only.
Page admins. An Automation skips comments and messages from the Page itself. A Page admin who comments from a personal profile is a commenter like any other, so the comment triggers the Automation.

Private replies

A private reply sends a one-time DM to the person who commented. Send it with POST /v1/inbox/comments/{postId}/{commentId}/private-reply. Facebook allows one private reply per comment, within 7 days of the comment. A second reply, or a comment older than 7 days, returns 400 platform.facebook.private_reply_ineligible.

Direct messages and the messaging window

A Page can message a person only inside the 24-hour messaging window that the person’s last message opened. Outside it, the send returns 400 platform.facebook.window_closed.

Message types. Text and attachments. A DM send ignores quick_replies, buttons, and cards: it delivers only the text. Buttons work on a private reply. Each attachment in attachments[] has a source_type (url, media_id, or platform_attachment_id) and a type. type is required for platform_attachment_id, or the request returns 400 validation.attachment_type_required. Field rules are in Direct messages.
Reactions. POST /v1/inbox/conversations/{id}/messages/{messageId}/reaction reacts to a message, and DELETE on the same path removes the reaction.
Delivery status. dm.status.sent, dm.status.delivered, and dm.status.read events follow each DM you send.
No message tags. A message_tag on a Facebook DM, including HUMAN_AGENT, is not sent: the DM goes out untagged and the 24-hour window applies.

Mentions

GET /v1/accounts/{id}/mentions returns the posts that tag the Page. A mention inside a comment is not in that list: it arrives as a mention.received event. Reply to a mention with POST /v1/accounts/{id}/mentions/reply, which posts a public comment. Details are in Mentions.

Page insights

GET /v1/platforms/facebook/accounts/{id}/summary returns the Page’s followers, views, reach, post engagements, and net follower change over the trailing 30 days.

curl "https://api.social-api.ai/v1/platforms/facebook/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/summary" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "follower_count": 12840,
  "views": 48210,
  "reach": 31975,
  "interactions": 2216,
  "net_follows": 154,
  "period_start": "2026-09-17T09:00:00Z",
  "period_end": "2026-10-17T09:00:00Z"
}

interactions counts post engagements, and net_follows is new follows minus unfollows over the period. GET /v1/platforms/facebook/accounts/{id}/insights/daily returns one point per day, oldest first. days sets how many trailing days, from 1 to 365 (default 365). A day with no data is left out.

curl "https://api.social-api.ai/v1/platforms/facebook/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/insights/daily?days=2" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "data": [
    {"date": "2026-10-15", "followers": 12831, "views": 1620, "reach": 1104, "interactions": 71},
    {"date": "2026-10-16", "followers": 12840, "views": 1755, "reach": 1187, "interactions": 83}
  ]
}

followers is the count at the end of the day. views, reach, and interactions are that day’s totals. Both routes take an optional page_id, the id from GET /v1/accounts/{id}/pages. Without it they report on the account’s default Page. Both are free, need the accounts:read scope on a scoped API key, and have no MCP tool. Both need the read_insights scope, requested since 2026-10-17 with the analytics.read permission. Post metrics in Analytics do not need it.

HTTP	Code	When it occurs
400	`validation.days_invalid`	`days` is below 1 or above 365
403	`platform.facebook.insights_scope_missing`	The Page was connected before 2026-10-17, its login declined `read_insights`, or the person who connected it does not hold the Analyze task on the Page. A reconnect fixes the first two; for the third, grant the Analyze task on Facebook, then reconnect
403	`account.permission_missing`	The account does not have the `analytics.read` permission
404	`account.not_found`	The account does not exist
404	`resource.not_found`	`page_id` is not an active Page of the account, or the account has no default Page
501	`resource.not_supported`	`{id}` is not a Facebook account
502	`platform.facebook.<code>` or `platform.facebook.api_error`	Facebook returned an error, where `<code>` is Meta’s error code, or failed with no code: see Errors

Reviews

SocialAPI does not read Facebook reviews: Meta deprecated Page recommendations in Graph API v22.0. GET /v1/inbox/reviews/{account_id} for a Facebook account returns 422 account.platform_unsupported, and no other call replaces it.

Webhook events

Facebook Pages emit these events to your webhook endpoints. Payloads are in Webhook events.

Event	When it fires
`comment.received`	A person comments on a Page post, or edits a comment
`mention.received`	The Page is tagged in a post or a comment
`dm.received`	A person sends a Messenger message
`dm.sent`	A message left the Page, including one sent from Meta Business Suite
`dm.referral`	A person opened a conversation from an ad or referral link without sending a message
`dm.postback`	A person tapped a button on a private reply
`dm.status.sent`, `dm.status.delivered`, `dm.status.read`	Facebook accepted, delivered, or showed as read a DM you sent
`account.connected`	You finished connecting or reconnecting the account
`account.disconnected`	The person revoked access on Facebook, or SocialAPI flagged the account for reconnection (`reconnect_required: true`, see `reason`)
`account.updated`	The account lost permissions you did not remove yourself (`change` is `permissions_reduced`)
`page.removed`	A Page was removed from the login
`post.published`, `post.partial`, `post.failed`	A post to this account finished: see Delivery

Every post.* event in Webhook events is emitted for this platform.

Limits

Limit	Value
Post text	63,206 characters
Photo	10 MB: JPEG, PNG, GIF, or WebP
Video	4 GB and 240 minutes: MP4, QuickTime, or AVI
Multi-photo album	2 to 10 images
Posts	100 per 24 hours and 25 per hour for each Page: see Posting velocity caps
Private reply	1 per comment, within 7 days
Facebook’s own rate limit	`429 platform.facebook.rate_limit`. Credit rules: see when a credit comes back

A Page access token does not expire on its own. Reconnect only when a call returns 401 platform.facebook.auth, for example after the person revoked access.

Scopes

SocialAPI’s Meta app requests these scopes at connect. You apply for no app review. Each scope belongs to the account permissions in the last column, and the consent screen asks for the scopes of the permissions you selected. The scopes marked Every account are always requested.

Scope	Used for	Permissions
`pages_show_list`	List the Pages the person manages	Every account
`business_management`	List Pages owned through a Business Portfolio	Every account
`pages_read_engagement`	Read likes, comments, and shares on Page posts	Every account
`pages_read_user_content`	Read posts and comments that people make on the Page	`comments.read`, `comments.write`
`pages_manage_engagement`	Reply to, hide, delete, and like comments	`comments.write`
`pages_manage_metadata`	Subscribe the Page to webhook events	Every account
`pages_messaging`	Send and receive Messenger DMs	`messages.read`, `messages.write`
`pages_manage_posts`	Create, edit, and delete Page posts	`posts.write`
`read_insights`	Page insights. A login that declines it keeps `analytics.read`	`analytics.read`
`public_profile`	Identify the person who connected	Every account

Facebook asks for messages as 1 scope, covering both reading and writing, so the consent screen shows the broader scope. The account stays limited to the permissions you selected: an account connected with messages.read alone cannot send messages.

Facebook publishing: fields, media rules, and quirks for publishing
Connect accounts: the shared connect flow
Automations: comment-to-DM flows
Platforms: the capability matrix
Errors: every error code

​At a glance

​Capabilities

​Connect an account

​Pages of an account

​One login, many brands

​Comments

​Private replies

​Direct messages and the messaging window

​Mentions

​Page insights

​Reviews

​Webhook events

​Limits

​Scopes

​Related

At a glance

Capabilities

Connect an account

Pages of an account

One login, many brands

Comments

Private replies

Direct messages and the messaging window

Mentions

Page insights

Reviews

Webhook events

Limits

Scopes

Related