facebook-page — Universal Meta Graph API Skill

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

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

---

STEP 1 — Load Credentials

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

$cfg    = Get-Content "$HOME/.config/fb-page/credentials.json" -Raw | ConvertFrom-Json
$token  = $cfg.FB_PAGE_TOKEN
$pageId = $cfg.FB_PAGE_ID

If the file doesn't exist, guide setup. Required fields:

Field	Purpose
FB_PAGE_TOKEN	Never-expiring Page access token — used for all API calls
FB_PAGE_ID	Numeric Facebook Page ID
FB_APP_ID	Meta App ID — only needed during token exchange
FB_APP_SECRET	Meta App Secret — only needed during token exchange

One-time token exchange setup:

# Provide: $appId, $appSecret, $shortToken (from Graph API Explorer), $pageId
# 1. Exchange for long-lived user token
$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"
# 2. Get never-expiring Page token
$r2 = Invoke-RestMethod "https://graph.facebook.com/v25.0/$pageId?fields=access_token&access_token=$($r1.access_token)"
$pageToken = $r2.access_token
# 3. Save — only these four fields, nothing else
@{
    FB_PAGE_ID    = $pageId
    FB_PAGE_TOKEN = $pageToken
    FB_APP_ID     = $appId
    FB_APP_SECRET = $appSecret
} | ConvertTo-Json | Set-Content "$HOME/.config/fb-page/credentials.json" -Encoding UTF8

Restrict file permissions immediately after saving:

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

⚠️ 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

Common Endpoints

What user wants	Method	Endpoint
Post text	POST	/$pageId/feed — body: message
Post with image	POST	/$pageId/photos — multipart: source + message
Post with video	POST	/$pageId/videos — multipart: source + description
Post with link	POST	/$pageId/feed — body: message + link
Delete a post	DELETE	/{post-id}
Schedule a post	POST	/$pageId/feed — body: message + published=false + scheduled_publish_time (unix timestamp)
Get recent posts	GET	/$pageId/published_posts?fields=id,message,created_time&limit=10
Get page info	GET	/$pageId?fields=name,fan_count,followers_count,about
Like a post	POST	/{post-id}/likes
Get comments	GET	/{post-id}/comments?fields=message,from,created_time
Reply to comment	POST	/{comment-id}/comments — body: message
Hide comment	POST	/{comment-id} — body: is_hidden=true
Delete comment	DELETE	/{comment-id}
Get page insights	GET	/$pageId/insights?metric=page_fans,page_impressions&period=day
Get post insights	GET	/{post-id}/insights?metric=post_impressions,post_reactions_by_type_total
List events	GET	/$pageId/events?fields=name,start_time,description
Create event	POST	/$pageId/events — body: name, start_time, description
List albums	GET	/$pageId/albums?fields=name,count
Get page roles	GET	/$pageId/roles
Publish draft post	POST	/{post-id} — body: is_published=true

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

Multipart (image/video upload):

$boundary  = [System.Guid]::NewGuid().ToString()
$fileBytes = [System.IO.File]::ReadAllBytes($filePath)
$fileName  = [System.IO.Path]::GetFileName($filePath)
$stream    = New-Object System.IO.MemoryStream
$writer    = New-Object System.IO.StreamWriter($stream)
$writer.Write("--$boundary`r`nContent-Disposition: form-data; name=`"message`"`r`n`r`n$message`r`n")
$writer.Write("--$boundary`r`nContent-Disposition: form-data; name=`"access_token`"`r`n`r`n$token`r`n")
$writer.Write("--$boundary`r`nContent-Disposition: form-data; name=`"source`"; filename=`"$fileName`"`r`nContent-Type: image/jpeg`r`n`r`n")
$writer.Flush(); $stream.Write($fileBytes, 0, $fileBytes.Length)
$writer.Write("`r`n--$boundary--`r`n"); $writer.Flush()
$result = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$pageId/photos" -Method POST `
    -ContentType "multipart/form-data; boundary=$boundary" -Body $stream.ToArray() -ErrorAction Stop

Scheduled post — convert local time to Unix timestamp:

$runAt    = [datetime]"2026-03-15 09:00"
$unixTime = [int][double]::Parse(($runAt.ToUniversalTime() - [datetime]"1970-01-01").TotalSeconds)
$result   = Invoke-RestMethod -Uri "https://graph.facebook.com/v25.0/$pageId/feed" -Method POST `
    -Body @{ message="text"; published="false"; scheduled_publish_time=$unixTime; access_token=$token } -ErrorAction Stop

---

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
}

Code	Subcode	Meaning	Fix
100	—	Invalid parameter	Check the parameter values
102	—	Session expired	Re-run setup to get a new token
190	460	Token expired	Re-run setup with a new short-lived token
190	467	Invalid token	Re-run setup
200	—	Permission denied	Add the permission listed in error.message to your app
10	—	Permission denied (page)	Add pages_read_engagement or pages_manage_posts
230	—	Requires re-auth	Re-run setup
368	—	Temporarily blocked	Wait and retry; page may be rate-limited

Permissions Reference

Permission	Required for
pages_manage_posts	Create, delete, schedule posts
pages_read_engagement	Read posts, likes, comments, insights
pages_show_list	List pages you manage
pages_manage_metadata	Update page settings
pages_manage_engagement	Moderate comments, reply to reviews
pages_read_user_content	Read visitor posts and comments
pages_manage_ads	Manage ad campaigns on the page
pages_manage_instant_articles	Manage Instant Articles

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 5. Re-run setup with the new token

---

AGENT RULES

• Always load credentials first. If missing or incomplete, guide setup.
• Only use FB_PAGE_TOKEN and FB_PAGE_ID for API calls. FB_APP_ID and FB_APP_SECRET are for token exchange only.
• Never write extra fields to the credentials file (no owner IDs, conv IDs, or third-party keys).
• Remove FB_APP_SECRET from credentials.json after token exchange — it is not needed for API calls.
• Least-privilege: only request the permissions your use case needs. Do not request pages_manage_ads or pages_manage_instant_articles unless explicitly needed.
• Rotate FB_PAGE_TOKEN periodically via Graph API Explorer, and immediately if the host is ever compromised.
• All API calls go to graph.facebook.com only. No external forwarding, no third-party services.
• Construct API calls inline from user intent — don't 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.