instagram-page - Universal Instagram Graph API Skill

Constructs and executes Instagram Graph API calls inline based on what the user wants. No scripts needed.

Requires an Instagram Business or Creator account linked to a Facebook Page. Personal Instagram accounts are not supported by the Instagram Graph API.

API version: v25.0 Base URL: https://graph.facebook.com/v25.0

---

STEP 1 - Load Credentials

Credentials are stored in ~/.config/instagram-page/credentials.json.

$cfg      = Get-Content "$HOME/.config/instagram-page/credentials.json" -Raw | ConvertFrom-Json
$token    = $cfg.IG_ACCESS_TOKEN
$igUserId = $cfg.IG_USER_ID

If the file does not exist, guide setup. Required fields:

| Field | Purpose | |---|---| | IG_ACCESS_TOKEN | Long-lived User access token - used for all API calls | | IG_USER_ID | Instagram-scoped Business/Creator User ID (numeric) | | IG_APP_ID | Meta App ID - only needed during token exchange | | IG_APP_SECRET | Meta App Secret - only needed during token exchange |

Prerequisites:

1. Instagram account must be a Business or Creator account
2. The Instagram account must be linked to a Facebook Page
3. A Meta App with instagram_basic, instagram_content_publish, instagram_manage_comments, instagram_manage_insights permissions

One-time token exchange setup:

# Provide: $appId, $appSecret, $shortToken (from Graph API Explorer with IG permissions), $fbPageId
# 1. Exchange short-lived token for long-lived user token (valid 60 days)
$r1 = Invoke-RestMethod "https://graph.facebook.com/oauth/access_token?grant_type=fb_exchange_token&client_id=$appId&client_secret=$appSecret&fb_exchange_token=$shortToken"
$longToken = $r1.access_token
# 2. Get Instagram Business Account ID linked to your Facebook Page
$r2 = Invoke-RestMethod "https://graph.facebook.com/v25.0/$fbPageId?fields=instagram_business_account&access_token=$longToken"
$igUserId = $r2.instagram_business_account.id
# 3. Save - only these four fields
@{
    IG_USER_ID      = $igUserId
    IG_ACCESS_TOKEN = $longToken
    IG_APP_ID       = $appId
    IG_APP_SECRET   = $appSecret
} | ConvertTo-Json | Set-Content "$HOME/.config/instagram-page/credentials.json" -Encoding UTF8

Restrict file permissions immediately after saving:

# Windows
icacls "$HOME/.config/instagram-page/credentials.json" /inheritance:r /grant:r "$($env:USERNAME):(R,W)"
# macOS / Linux
# chmod 600 ~/.config/instagram-page/credentials.json

Refresh token before it expires (every ~50 days):

$r = Invoke-RestMethod "https://graph.facebook.com/oauth/access_token?grant_type=ig_refresh_token&access_token=$token"
$cfg.IG_ACCESS_TOKEN = $r.access_token
$cfg | ConvertTo-Json | Set-Content "$HOME/.config/instagram-page/credentials.json" -Encoding UTF8

Delete IG_APP_SECRET from credentials.json after setup - it is not needed for API calls. Never commit this file to version control. It contains long-lived secrets. This skill makes no external calls other than to graph.facebook.com. No data is forwarded to third parties.

---

STEP 2 - Figure Out the API Call

Instagram publishing uses a two-step flow for most media types:

1. Create a media container - uploads/registers the media, returns a creation_id
2. Publish the container - makes it live on Instagram

Common Endpoints

| What user wants | Method | Endpoint | |---|---|---| | Post single photo | POST x2 | Step 1: /$igUserId/media Step 2: /$igUserId/media_publish | | Post reel (video) | POST x2 | Step 1: /$igUserId/media (media_type=REELS) Step 2: /$igUserId/media_publish | | Post story | POST x2 | Step 1: /$igUserId/media (media_type=STORIES) Step 2: /$igUserId/media_publish | | Post carousel | POST x3+ | Step 1: item containers Step 2: carousel container Step 3: publish | | Get recent media | GET | /$igUserId/media?fields=id,caption,media_type,timestamp,like_count,comments_count | | Get account info | GET | /$igUserId?fields=username,name,biography,followers_count,media_count | | Get comments | GET | /{media-id}/comments?fields=text,username,timestamp | | Reply to comment | POST | /{comment-id}/replies body: message | | Delete comment | DELETE | /{comment-id} | | Hide/show comment | POST | /{comment-id} body: hide=true/false | | Get media insights | GET | /{media-id}/insights?metric=impressions,reach,likes,comments,shares,saved | | Get account insights | GET | /$igUserId/insights?metric=impressions,reach,follower_count&period=day | | Get hashtag ID | GET | ig/hashtags?user_id=$igUserId&q=hashtag | | Search hashtag media | GET | /{hashtag-id}/top_media?user_id=$igUserId&fields=id,caption,media_type | | Get tagged media | GET | /$igUserId/tags?fields=caption,media_url,timestamp |

API Call Patterns

GET:

$result = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/ENDPOINT?access_token=$token" -ErrorAction Stop

POST (form body):

$result = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/ENDPOINT" -Method POST `
    -Body @{ field1="value1"; field2="value2"; access_token=$token } -ErrorAction Stop

DELETE:

$result = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/{id}?access_token=$token" -Method DELETE -ErrorAction Stop

Publishing Patterns

Single photo post:

# image_url must be publicly accessible
$container = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$igUserId/media" -Method POST `
    -Body @{ image_url=$imageUrl; caption=$caption; access_token=$token } -ErrorAction Stop
$post = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$igUserId/media_publish" -Method POST `
    -Body @{ creation_id=$container.id; access_token=$token } -ErrorAction Stop
Write-Host "Published post ID: $($post.id)"

Reel post (video):

# video_url must be publicly accessible MP4 (H.264, AAC audio, max 1GB, max 60s for feed)
$container = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$igUserId/media" -Method POST `
    -Body @{ media_type="REELS"; video_url=$videoUrl; caption=$caption; share_to_feed="true"; access_token=$token } -ErrorAction Stop
# Poll for processing status - video upload is async
do {
    Start-Sleep -Seconds 5
    $status = Invoke-RestMethod "https://graph.facebook.com/v25.0/$($container.id)?fields=status_code&access_token=$token"
} while ($status.status_code -eq "IN_PROGRESS")
if ($status.status_code -ne "FINISHED") { throw "Video processing failed: $($status.status_code)" }
$post = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$igUserId/media_publish" -Method POST `
    -Body @{ creation_id=$container.id; access_token=$token } -ErrorAction Stop
Write-Host "Published reel ID: $($post.id)"

Carousel post (2-10 images/videos):

# Create item containers for each media URL
$itemIds = @()
foreach ($url in $mediaUrls) {
    $item = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$igUserId/media" -Method POST `
        -Body @{ image_url=$url; is_carousel_item="true"; access_token=$token } -ErrorAction Stop
    $itemIds += $item.id
}
# Create carousel container
$carousel = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$igUserId/media" -Method POST `
    -Body @{ media_type="CAROUSEL"; children=($itemIds -join ","); caption=$caption; access_token=$token } -ErrorAction Stop
# Publish
$post = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$igUserId/media_publish" -Method POST `
    -Body @{ creation_id=$carousel.id; access_token=$token } -ErrorAction Stop
Write-Host "Published carousel ID: $($post.id)"

Story:

$container = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$igUserId/media" -Method POST `
    -Body @{ media_type="STORIES"; image_url=$imageUrl; access_token=$token } -ErrorAction Stop
$post = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$igUserId/media_publish" -Method POST `
    -Body @{ creation_id=$container.id; access_token=$token } -ErrorAction Stop
Write-Host "Published story ID: $($post.id)"

Image/video URLs must be publicly accessible - local files are not accepted by the API. Upload to a public server or CDN before calling. Instagram limits ~50 API-published posts per 24h.

---

STEP 3 - Handle Errors

try {
    # ... API call ...
} catch {
    $err     = $_.ErrorDetails.Message | ConvertFrom-Json -ErrorAction SilentlyContinue
    $code    = $err.error.code
    $subcode = $err.error.error_subcode
    $msg     = $err.error.message
    Write-Host "Error $code/$subcode : $msg"
}

| Code | Subcode | Meaning | Fix | |---|---|---|---| | 100 | - | Invalid parameter | Check parameter values; image/video URL must be public | | 102 | - | Session expired | Refresh token - run the refresh snippet in STEP 1 | | 190 | 460 | Token expired (60 days) | Refresh token - run the refresh snippet in STEP 1 | | 190 | 467 | Invalid token | Re-run full setup to get a new token | | 200 | - | Permission denied | Add the missing permission to your Meta App and regenerate token | | 10 | - | Permission denied (IG scope) | Add permission listed in error.message; re-run setup | | 24 | - | No linked IG Business account | Link Instagram account to your Facebook Page in Instagram settings | | 32 | - | Page request limit reached | Wait and retry; hourly rate limit hit | | 368 | - | Temporarily blocked | Wait and retry; account may be temporarily restricted | | 9007 | - | Publishing limit reached | Instagram limits ~50 API-published posts per 24h | | 2207026 | - | Video format invalid | MP4 required; H.264 video, AAC audio, max 1GB, 60s for feed reels |

Permissions Reference

| Permission | Required for | |---|---| | instagram_basic | Read account info, media list | | instagram_content_publish | Create and publish posts, reels, stories, carousels | | instagram_manage_comments | Read, reply to, hide, delete comments | | instagram_manage_insights | Access account and media insights | | pages_show_list | List Facebook Pages (needed during IG account lookup) | | pages_read_engagement | Read Facebook Page linked to Instagram account |

If a permission is missing:

1. Go to Meta for Developers
2. Select your app -> Permissions and Features
3. Add the required permission
4. Regenerate token via Graph API Explorer with the permission checked
5. Re-run setup with the new token

---

AGENT RULES

• Always load credentials first. If missing or incomplete, guide setup.
• Only use IG_ACCESS_TOKEN and IG_USER_ID for API calls. IG_APP_ID and IG_APP_SECRET are for token exchange only.
• Delete IG_APP_SECRET from credentials.json after token exchange - it is not needed for API calls.
• Token expiry: IG_ACCESS_TOKEN expires every 60 days. Remind the user to refresh before expiry using the refresh snippet in STEP 1. Rotate immediately if the host is ever compromised.
• Two-step publishing: always create a container first, then publish. Never try to publish in a single API call.
• Public URLs only: image/video URLs must be publicly accessible. If the user provides a local file path, tell them to upload it to a public server or CDN first.
• Reel processing: poll status_code until FINISHED before publishing - video processing is async and can take minutes.
• Least-privilege: only request the permissions the use case needs.
• All API calls go to graph.facebook.com only. No external forwarding, no third-party services.
• Construct API calls inline from user intent - do not look for script files.
• On any error: parse error.code + error.error_subcode, map to the table above, tell the user exactly what to do.
• If a permission is missing: name it, link to Meta for Developers, say to re-run setup.
• Business/Creator only: if the user has a personal Instagram account, tell them to convert it to Business or Creator in Instagram settings first - personal accounts are not supported by the Instagram Graph API.