Instagram Business
Publish to Instagram accounts linked to Facebook Pages (pictures, carousels, reels and stories, with collaborators and comments). What to register at Meta for Developers.
Staqly publishes to Instagram professional accounts linked to a Facebook Page through the Instagram Graph API with Facebook Login: the person signs in on facebook.com, staqly lists the Instagram accounts of their Pages, and each account they pick becomes its own channel. A published target links to the post on instagram.com.
An account without a Facebook Page connects through the Instagram channel instead (Instagram Login). Publishing works the same on both.
What you need
- A Meta app with Facebook Login for Business and the Instagram product, registered once
per server. Its keys go into the server's environment (
.env), the same way locally and in the cloud (see Developer apps). The app that serves Facebook Pages can serve this channel too. - Media storage Instagram can reach. Instagram does not take uploads: it downloads every picture
and video from a link. Staqly hands it a time-limited link to the file in
S3-compatible storage, so a server that keeps media on its own disk
can't publish to Instagram (the target fails and says why). Locally, the bucket needs an address
on the internet, for example a tunnel to it set as
S3_PUBLIC_URL. - An Instagram account set to Business or Creator and linked to a Facebook Page (Page settings → Linked accounts), and a Facebook account with a role on that Page.
Create the app
At Meta for Developers, click Create app and choose Business. Add Facebook Login for Business and Instagram (API setup with Facebook login), then set:
| Where | What |
|---|---|
| Facebook Login for Business → Settings → Valid OAuth Redirect URIs | your dashboard's /channels/callback/instagram_business, for example https://staqly.example.com/channels/callback/instagram_business. Meta takes https:// addresses only, so locally use a tunnel to localhost:8080 |
| App roles → Roles | the people who may connect while the app is in development |
Copy the App ID and App secret from App settings → Basic (the Meta app's own keys, not the Instagram app ID).
Give staqly the keys
Put them in the server's environment and restart it:
PROVIDER_INSTAGRAM_BUSINESS_CLIENT_ID=your-meta-app-id
PROVIDER_INSTAGRAM_BUSINESS_CLIENT_SECRET=your-meta-app-secret- Docker:
docker run ... --env-file .env ghcr.io/staqly/staqly:latest, or-e PROVIDER_INSTAGRAM_BUSINESS_CLIENT_ID=.... - Binary: export both in your shell, then run
staqly serveorstaqly service install(the service keepsPROVIDER_*settings).
Until both are set, Instagram Business shows as soon in Channels → Add channel.
PROVIDER_INSTAGRAM_BUSINESS_ENABLED=false hides it altogether. A workspace may instead save its own
app over the API (PUT /v1/providers/instagram_business/app).
Connect the accounts
Connect with Facebook opens facebook.com, where the person signs in, chooses the Pages (and their Instagram accounts) the app may use and allows it. Staqly asks for these permissions:
| Permission | Why |
|---|---|
instagram_basic | Read the account's username, name and picture |
instagram_content_publish | Publish posts, carousels, reels and stories |
instagram_manage_comments | Post the comments of a post's thread |
pages_show_list | List the Pages the Instagram accounts are linked to |
pages_read_engagement | Read those Pages |
business_management | Also list the Pages a business portfolio owns or manages for clients |
Staqly then lists the Instagram accounts of those Pages: pick one or more, and each becomes a
channel showing the account's name, @username and picture. Connecting the same account again
reconnects its channel. Without instagram_manage_comments the channel connects, but a post's
comments are not sent on it.
If staqly says none of your Pages has an Instagram account, link one in the Page's settings, or connect again and choose the right Pages when Facebook asks.
Before other people connect
While the app is in development, only people with a role on it can connect. Before your customers connect their accounts, Meta reviews the app: App Review for each permission above (a screen recording of staqly using it) and Business Verification of your company.
The sign-in
Each channel keeps the token of the Page its account is linked to, which does not run out. The channel turns Needs reconnect when the person removes the app, changes their password, loses their role on the Page, or the account is unlinked from it.
Limits
| Text | 2,200 characters; up to 30 hashtags |
| Media | at least one file: up to 10 pictures and videos (a carousel), one video for a reel, one file for a story |
| Pictures | JPEG only, up to 8 MB; feed pictures 4:5 to 1.91:1 (the composer flags a picture that doesn't fit) |
| Posts | Instagram takes up to 100 posts a day per account through its API |
Settings per post
| Setting | What it does |
|---|---|
Post as (post_type) | post (default; several files make a carousel, a single video goes out as a reel), reel or story (stories take no caption) |
Also show the reel in the feed (share_to_feed) | Reels only; on by default |
Collaborators (collaborators) | Feed posts: up to 3 usernames invited as collaborators; the post shows on their profiles once they accept |
Over the API: {"post_type": "reel", "share_to_feed": "false"} in the target's settings.
Comments
A post's thread goes out as comments under the post, in order and after their delays: for example a first comment with hashtags. Comments take text only; stories have none.
When publishing fails
| Instagram says | Staqly does |
|---|---|
| The sign-in expired or was revoked | Marks the channel Needs reconnect and fails the target; reconnect it from the row's menu |
| Rate limit, Instagram unavailable, a media download that timed out | Retries through the job queue (after 1, 5, then 15 minutes) |
| A refused picture (format, size, shape), the daily limit, a restricted account | Fails the target with Instagram's reason; retrying would not help, so it does not |
Instagram has no way to ask "did this post go out?", and a new attempt would make a new post. So when staqly sent the post but its answer never came, the target fails with "may have published" instead of trying again: check the profile before you post it again.
Publish pictures, carousels, reels and stories to an Instagram Business or Creator account, with collaborators and comments. What to register at Meta for Developers.
Facebook Page
Publish posts, pictures, videos, reels and stories to Facebook Pages, with comments. What to register at Meta for Developers and how to pick the Pages.