Posts
Publish stories to a Facebook Page via API
With format story and integration_slug facebook, Connect publishes the media as a story on the Page your customer connected, with the same POST /posts call as the other formats.
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-story-23",
"format": "story",
"media": [
{
"type": "image",
"url": "https://cdn.example.com/story.jpg"
}
]
}What you can do
- Publish a story from a public https:// image or video URL.
- Target the Page by connection (customer_integration) or by integration_slug and source_name.
- Retry safely with Idempotency-Key.
Rules and limits
- Stories carry no caption: do not send caption.
- The story format has no options in the facebook block.
- Up to 10 media per call, each one becomes a story, published in order. The network checks every file before the first one goes out, so a broken file never leaves the sequence half published.
- The answer is 202: publishing runs in the background. Follow it with GET /posts/{uuid}.
- external_reference is required and prevents publishing the same reference twice on the account (409).
Main fields
| Field | Type | Required | Description |
|---|---|---|---|
| external_reference | string | Yes | The post's id in your system (up to 100 characters). Prevents publishing the same post twice on the same account. |
| format | string | Yes | Post format. On Instagram: feed, reels or story. On Facebook: feed, reels or story. |
| media | array | Yes | List of media, in order. Each item has type and url. |
| media.type | string | Yes | Media type: image, video or document (document is LinkedIn only). |
| media.url | string | Yes | Public https:// URL the network can download (up to 2048 characters). |
Who it is for
Quick notices
The SaaS publishes a deal-of-the-day story on the customer's Page with one click from the user.
Store chain
Publish the same vertical artwork as a story on the Pages of several locations.
AI agent
An agent turns a launch into a vertical image and publishes it as a story.
Works with
Facebook
Frequently asked questions
Can I add a caption to the story?
No. Stories carry no caption.
Are there extra facebook block options?
Not for story. The facebook block has link on feed and title and cover on reels.
How do I follow the publication?
POST /posts answers 202. Check GET /posts/{uuid}.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
