Skip to content

Connect channels

Instagram publishing and insights

Publish and schedule photos, videos, carousels, Reels and Stories, and read account and post insights.

This page applies to Instagram accounts that are already connected. Publishing requires the instagram_content_publish permission; insights require instagram_manage_insights. Without them, the route answers 403 instagram_scope_missing until you reconnect the account.

Meta does not schedule posts: Messajo stores the request and publishes at the set time. In the panel, use Publications → New publication; through the API, POST /v1/publications.

New publication screen with account, type, media, caption counters and the choice between publishing now and scheduling

type Media Note
photo 1 image Feed post
video 1 video Becomes Reels with share_to_feed always on (Meta discontinued plain feed videos)
reel 1 video Accepts a cover (cover), thumb_offset_ms, share_to_feed and audio_name
carousel 2 to 20 items, images and/or videos One container per item and one for the carousel
story 1 image or video No visible caption

Each item comes as a media_id (file uploaded with POST /v1/media and purpose=publication) or as a public url. They also accept alt_text, user_tags, collaborators (up to 3) and location_id.

Rule Value
Caption up to 2,200 characters, 30 hashtags and 20 mentions (@)
Image JPEG, up to 8 MiB. PNG and WebP sent by media_id are converted to JPEG before publishing
Video MP4 or MOV, up to 300 MiB (Stories up to 100 MiB)
Scheduling from now up to 75 days ahead
Meta quota 100 publications per account in a rolling 24 h (GET /v1/connections/{id}/publishing-limit)

Outside these rules, the answer is 422 validation_failed with the field in details.

Meta downloads the media from the URL: it must be reachable from the internet. A media_id becomes a signed S3 storage link valid for 24 h. A private-network URL is rejected with 422 media_url_not_public.

An empty scheduled_at (or one within the next minute) publishes now; in the future, the publication is Scheduled and a task runs at the right time, with a sweep every minute as a safety net. While it is scheduled or queued, you can edit it (PATCH /v1/publications/{id}) or cancel it (POST /v1/publications/{id}/cancel); after that, publication_not_editable.

status What happens
scheduled Waiting for the set time
queued Queued to publish. With Meta’s quota full, it tries again every hour; 24 h past the time, it fails with publishing_limit_reached
creating Creating the media containers on Meta
processing Meta is processing the media. More than 30 min fails with container_timeout
publishing Asking for the publication
published Published, with external_media_id and permalink
failed Failed; the reason is in error (Messajo code + Meta code and status)
canceled Canceled by you

The publication.published and publication.failed events go out (catalog).

If Meta does not answer the publish request (timeout, 5xx), there is no way to know whether the post went out. Messajo does not publish again: it checks the container status on Meta. If it was already published, it marks published and looks for the post; if the container is ready and not published, it tries once more; if it is still processing, it waits. If it was published but the post was not found, it stays published without external_media_id, and that publication does not accept retry. A regular failed publication can be retried with POST /v1/publications/{id}/retry, which creates new containers.

In the panel, Insights shows the chosen account over 7, 28 or 90 days: reach, views, accounts engaged, interactions, followers gained and lost, the daily series and this month’s audience. Below, the posts with each one’s metrics.

Insights screen with reach and engagement cards, the daily chart and the posts table

/v1 route What it returns
GET /connections/{id}/insights Account metrics: reach, views, accounts_engaged, total_interactions, likes, comments, shares, saves, replies, reposts, follows_and_unfollows, profile_links_taps (per day) and follower_demographics, engaged_audience_demographics
GET /connections/{id}/posts · /posts/{post_id} The account’s posts, with likes and comments
GET /connections/{id}/posts/{post_id}/insights Post metrics, by type (feed, Reels or story)
  • Delay: Meta can take up to 48 h to update the numbers. Messajo caches each query for 15 min.
  • impressions was discontinued by Meta and is rejected with validation_failed.
  • A carousel item has no insights of its own: 422 insights_not_available. Neither does a story with an audience below 5 people.
  • Stories: a story’s metrics disappear 24 h after it expires, and the story insights webhook is still to be confirmed on the unified login. So Messajo takes a snapshot of the active stories every hour; the insight of an expired story comes from that snapshot, with source: "snapshot" and the time in captured_at (in the panel, “captured at …”).