Posts

Publish to a Facebook Page via API

With format feed and integration_slug facebook, Connect publishes to the Page your customer connected. The same POST /posts call covers text, links and photos.

The request

POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "external_reference": "fb-post-901",
  "format": "feed",
  "caption": "Conheça a novidade da semana",
  "media": [
    {
      "type": "image",
      "url": "https://cdn.example.com/foto1.jpg"
    },
    {
      "type": "image",
      "url": "https://cdn.example.com/foto2.jpg"
    }
  ]
}

What you can do

  • Publish a text-only post.
  • Share a link with facebook.link.
  • Publish up to 10 photos in a single post.
  • Target the Page by connection (customer_integration) or by integration_slug and source_name.

Rules and limits

  • The feed needs at least a caption, a link or media.
  • The caption goes up to 2200 characters.
  • A post with a link does not accept media.
  • Video on the feed is refused: Page video goes as reels.
  • The answer is 202: publishing runs in the background. Follow it with GET /posts/{uuid}.
  • external_reference is required (409 if an equal publication exists) and Idempotency-Key avoids duplicating.

Main fields

FieldTypeRequiredDescription
external_referencestringYesThe post's id in your system (up to 100 characters). Prevents publishing the same post twice on the same account.
formatstringYesPost format. On Instagram: feed, reels or story. On Facebook: feed, reels or story.
captionstringNoPost text. Up to 2200 characters. Stories carry no caption.
mediaarrayYesList of media, in order. Each item has type and url.
media.urlstringYesPublic https:// URL the network can download (up to 2048 characters).
facebook.linkstringNoLink shared on the post (up to 2048 characters). Feed only. A post with a link carries no media.

Who it is for

  • Social media manager

    The user writes the post in your SaaS and it goes out on the Facebook Page they connected.

  • Store announcements

    A store chain publishes the same announcement, with photos, on dozens of Pages.

  • AI agent

    An agent summarizes a news item and publishes the text with the link on the customer's Page.

Works with

  • Facebook

Frequently asked questions

Can I publish video on the Page feed?

No. Video goes as reels. The feed takes text, a link or photos.

How many photos fit in a post?

Up to 10. A post with a link carries no media.

Does it publish to a personal profile?

No. This format is for Facebook Pages, with integration_slug facebook.

Related

See everything you can do with Posts

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.