Instagram

Channel quick reference

Property	Business	Standalone
Provider identifier	instagram-business	instagram-standalone
Max content length	2200 characters	2200 characters
Required attachments	At least 1 (rejected at scheduled if missing)	At least 1
Reel / carousel detection	Auto (1 video → Reel, >1 image → carousel)	Auto
OAuth setup	Instagram	Instagram

Both providers expose the same CLI surface — the only difference is which integration id you target. Capture the id from integrations:list:

INSTAGRAM_ID=$(openquok integrations:list 
  | jq -r '.[] | select(.identifier | startswith("instagram")) | .id')

If you have both variants connected, pin the specific one:

IG_BUSINESS_ID=$(openquok integrations:list 
  | jq -r '.[] | select(.identifier=="instagram-business") | .id')
IG_STANDALONE_ID=$(openquok integrations:list 
  | jq -r '.[] | select(.identifier=="instagram-standalone") | .id')

Feed image post

Instagram requires at least one attachment, so always upload first:

MEDIA=$(openquok upload ./photo.jpg | jq -c '[{id: .data.id, path: .data.filePath}]')

openquok posts:create 
  -s "2026-01-15T10:00:00Z" 
  -t schedule 
  -c "Beautiful day! #photography" 
  -i "$INSTAGRAM_ID" 
  -m "$MEDIA"

Reel (single video)

A single video attachment is automatically published as a Reel:

MEDIA=$(openquok upload ./reel.mp4 | jq -c '[{id: .data.id, path: .data.filePath}]')

openquok posts:create 
  -s "2026-01-15T10:00:00Z" 
  -t schedule 
  -c "New reel — drop a 🔥 if you like it!" 
  -i "$INSTAGRAM_ID" 
  -m "$MEDIA"

Carousel (multi-image)

Pass more than one image and the provider publishes a carousel. The single -c caption is used for the carousel:

MEDIA=$(jq -nc 
  --arg id1 "$(openquok upload ./slide1.jpg | jq -r '.data.id')" 
  --arg p1  "$(openquok upload ./slide1.jpg | jq -r '.data.filePath')" 
  --arg id2 "$(openquok upload ./slide2.jpg | jq -r '.data.id')" 
  --arg p2  "$(openquok upload ./slide2.jpg | jq -r '.data.filePath')" 
  --arg id3 "$(openquok upload ./slide3.jpg | jq -r '.data.id')" 
  --arg p3  "$(openquok upload ./slide3.jpg | jq -r '.data.filePath')" 
  '[
    {id: $id1, path: $p1},
    {id: $id2, path: $p2},
    {id: $id3, path: $p3}
  ]')

openquok posts:create 
  -s "2026-01-15T10:00:00Z" 
  -t schedule 
  -c "Three sides of the same story 1/3 → 3/3" 
  -i "$INSTAGRAM_ID" 
  -m "$MEDIA"

Or, more idiomatically, loop over a directory and build the JSON in one pass:

MEDIA=$(for f in ./slides/*.jpg; do
  openquok upload "$f" | jq -c '{id: .data.id, path: .data.filePath}'
done | jq -s .)

openquok posts:create 
  -s "2026-01-15T10:00:00Z" 
  -t schedule 
  -c "Slides from today's talk" 
  -i "$INSTAGRAM_ID" 
  -m "$MEDIA"

Scheduled reply chain

providerSettings.instagram.replies[] carries follow-up comments that are published from the same account after the main post. Pass them on posts:create with --providerSettingsByIntegrationId:

openquok posts:create 
  -s "2026-01-15T10:00:00Z" 
  -t schedule 
  -c "Caption first, context in the replies 👇" 
  -i "$INSTAGRAM_ID" 
  -m "$MEDIA" 
  --providerSettingsByIntegrationId "$(jq -nc --arg id "$INSTAGRAM_ID" '
    {
      ($id): {
        instagram: {
          replies: [
            { message: "1/ Why this matters", delaySeconds: 60 },
            { message: "2/ How we built it",  delaySeconds: 180 },
            { message: "3/ What is next",     delaySeconds: 300 }
          ]
        }
      }
    }
  ')"

Cross-post to Threads in a single command

Both providers accept the same -c caption and -m payload. Pass both integration ids to fan out:

openquok posts:create 
  -s "2026-01-15T10:00:00Z" 
  -t schedule 
  -c "Same post, two networks" 
  -i "$INSTAGRAM_ID,$THREADS_ID" 
  -m "$MEDIA"

Override the caption per channel if Threads needs a shorter version:

openquok posts:create 
  -s "2026-01-15T10:00:00Z" 
  -t schedule 
  -c "Fallback caption" 
  -i "$INSTAGRAM_ID,$THREADS_ID" 
  -m "$MEDIA" 
  --bodiesByIntegrationId "$(jq -nc 
    --arg ig "$INSTAGRAM_ID" 
    --arg th "$THREADS_ID" '
      {
        ($ig): "Long Instagram-only caption with #hashtags and emoji 📸",
        ($th): "Short Threads-only caption."
      }
  ')"

Per-channel analytics

openquok analytics:platform "$INSTAGRAM_ID" -d 30 
  | jq '.[] | {label, percentageChange}'

openquok analytics:post <post-id> -d 30 
  | jq '.[] | {label, latest: .data[-1].total}'

Provider settings via CLI

Stories, trial reels, collaborators, and graduation strategy are available through --settings (flat keys merged into providerSettingsByIntegrationId):

openquok posts:create 
  -s "2026-01-15T10:00:00Z" 
  -t schedule 
  -c "Trial reel caption" 
  -i "$INSTAGRAM_ID" 
  -m "$MEDIA" 
  --settings '{"is_trial_reel":true,"graduation_strategy":"SS_PERFORMANCE","collaborators":["partner"]}'

Platform-specific settings

Configure per integration in the web composer Settings panel, or pass flat keys on the CLI with --settings (merged into providerSettingsByIntegrationId).

Setting	CLI / API key	Web composer (instagram.*)	Values
Post type	post_type	postType	post (feed/Reel) or story
Trial Reel	is_trial_reel	trialReel	true / false
Graduation strategy	graduation_strategy	graduationStrategy	MANUAL or SS_PERFORMANCE
Collaborators	collaborators	collaborators	Up to 3 usernames (no @ required)
Delayed replies	replies	replies	[{ "message": "…", "delaySeconds": 60 }]

Related