Instagram

Using hosted SimplePost? Follow connection requirements. The app uses Instagram Login for Business or Creator accounts; a linked Facebook Page is not required. The credential setup below is for direct SDK or self-hosted REST integrations. For local CLI OAuth, follow the CLI account setup with your own Meta app.

Content support

Current hosted app and core source

Capability	SimplePost support
Text / caption (characters)	2,200 caption
Media	Media required; 10 items max; Mixed media supported
Image size	8 MiB maximum
Video size	300 MiB maximum

These validation limits also match published SDK 1.3.1.

Provider permissions and quotas still apply. SimplePost storage can impose a lower upload limit. MB/GB use decimal bytes; MiB/GiB use binary bytes.

A single video is published as a Reel. Multiple items form a carousel. Media must be publicly fetchable; configure media storage when using local files.

Set up credentials

Choose one login flow and keep its token, account ID, and graphApi value together. A Facebook Page token cannot be sent to graph.instagram.com.

Instagram Login (default)

1. Switch the Instagram account to Business or Creator.
2. Create an app in Meta for Developers and configure Instagram API with Instagram Login. Register your integration's exact OAuth callback URL and add a test account while developing.
3. Request instagram_business_basic and instagram_business_content_publish. Complete Instagram authorization and exchange the returned authorization code for an Instagram user access token on your server.
4. Retain the Instagram account ID returned by the token exchange (user_id) with that token. SimplePost calls this field businessAccountId, including for Creator accounts.
5. Follow Meta's long-lived token exchange and refresh lifecycle. Keep app secrets on your server. Obtain the required app review/access level before connecting users outside your app's test roles.

Use Meta's Instagram Login guide for the authorization, token exchange, and refresh endpoints. This flow uses graph.instagram.com and does not require a Facebook Page.

Environment variables

INSTAGRAM_ACCESS_TOKEN=your_instagram_user_token
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_account_id

Both must be present. Environment credentials use graphApi: "instagram" by default; there is no environment variable to select Facebook Graph.

SDK example

After configuring those two variables:

import { post } from "@simple-post/sdk";

await post({
  content: {
    text: "Photo dump",
    media: [
      { type: "image", url: "https://cdn.example.com/photo1.jpg" },
      { type: "image", url: "https://cdn.example.com/photo2.jpg" },
    ],
  },
  platforms: ["instagram"],
});

Replace the sample URLs with public images you control. Alternatively pass accessToken, businessAccountId, and graphApi: "instagram" through options.instagram.credentials.

Facebook Login (existing integrations)

Use this path only when your integration obtains credentials through Instagram API with Facebook Login.

1. Connect the professional Instagram account to a Facebook Page you manage.
2. Configure Facebook Login in your Meta app. Request the applicable Instagram publishing and Page discovery permissions: instagram_basic, instagram_content_publish, pages_show_list, and pages_read_engagement. Meta may require additional business permissions depending on how Page access is assigned.
3. Authorize the Page owner/manager, exchange for a long-lived user token according to Meta's lifecycle, and call GET /me/accounts on Facebook Graph to obtain the Page access token and Page ID.
4. With that Page token, request GET /PAGE_ID?fields=instagram_business_account. Use the returned instagram_business_account.id as businessAccountId.
5. Pass the Page token and account ID with graphApi: "facebook" explicitly. Do not use the environment-only example above for this flow.

import { post } from "@simple-post/sdk";

const accessToken = process.env.FACEBOOK_PAGE_ACCESS_TOKEN;
const businessAccountId = process.env.INSTAGRAM_BUSINESS_ACCOUNT_ID;
if (!accessToken || !businessAccountId) throw new Error("Set the Facebook Page token and Instagram account ID");

await post({
  content: {
    text: "Hello from our Page-connected Instagram account",
    media: [{ type: "image", url: "https://cdn.example.com/photo.jpg" }],
  },
  platforms: ["instagram"],
  options: {
    instagram: { credentials: { accessToken, businessAccountId, graphApi: "facebook" } },
  },
});

FACEBOOK_PAGE_ACCESS_TOKEN here is a variable read by your example code, not an SDK Instagram environment fallback.

REST server account

Add this entry under accounts in the self-hosted REST server's accounts.json for Instagram Login:

{
  "id": "ig-professional",
  "platform": "instagram",
  "credentials": {
    "accessToken": "YOUR_INSTAGRAM_USER_TOKEN",
    "businessAccountId": "YOUR_INSTAGRAM_ACCOUNT_ID",
    "graphApi": "instagram"
  }
}

For Facebook Login, set graphApi to "facebook", use the Facebook Page token as accessToken, and use the Page's linked Instagram account ID as businessAccountId.