Instagram Auto-Posting — Developer Handoff

Everything a developer needs to finish connecting Instagram to the ICONIC client platform.
Last updated: 4 April 2026

1. The Full Client Journey (End to End)

2. What's Built vs What's Missing

3. Key Files

4. All API Endpoints

5. What Needs to Be Done (In Order)

Phase 1: Unblock the Configuration (Human Required)

A human with a Facebook account needs to do these steps. The onboarding guide at /iconic/instagram_onboarding.html walks through this click-by-click:

1. Switch the @iconicbyai Instagram account to a Business account (Instagram app → Settings → Account type → Business)
2. Create a Facebook Page (facebook.com → Pages → Create, or Facebook app → Menu → Pages → Create)
3. Link the Instagram account to that Facebook Page (Instagram → Edit Profile → Page → select the page)
4. Create a Meta Developer App at developers.facebook.com (type: Business, add Instagram product)
5. Copy the App ID and App Secret from the app's Settings → Basic page
6. Generate an access token via the Graph API Explorer with 4 permissions: instagram_basic, instagram_content_publish, pages_show_list, pages_read_engagement
7. Paste the App ID, App Secret, and token into the onboarding page → click "Connect" → auto-setup does the rest

Phase 2: Add Scheduled Posting Cron (Developer — 5 min)

The function processScheduledPosts() in instagram_manager.js already processes queued posts. It just needs to be called on a schedule.

Add this to serve_reports.js near the existing cron jobs (search for cron.schedule):

// Instagram scheduled posting — every 30 minutes
cron.schedule('*/30 * * * *', async () => {
  try {
    const igm = getIgManager();
    const count = await igm.processScheduledPosts();
    if (count > 0) console.log(`[IG Scheduler] Posted ${count} scheduled items`);
  } catch (e) {
    console.error('[IG Scheduler] Error:', e.message);
  }
}, { timezone: 'America/Chicago' });

Phase 3: Secure Admin Endpoints (Developer — 30 min)

All /api/instagram/admin/* endpoints currently have no auth. Add a check for an admin session or API key before each one. Pattern:

// Add at the top of each admin endpoint:
const adminEmails = ['[email protected]']; // or check a role
const sessionToken = parseCookies(req).iconic_session;
const email = getEmailFromSession(sessionToken);
if (!email || !adminEmails.includes(email)) {
  res.writeHead(401, { 'Content-Type': 'application/json' });
  return res.end(JSON.stringify({ ok: false, error: 'Admin access required' }));
}

Phase 4: Wire Up Admin Dashboard (Developer — 1-2 hours)

Iconic/instagram_admin.html has the UI built but needs its JavaScript completed to call the admin API endpoints (fetch clients, save config, check health, view history, queue posts).

Phase 5: Token Refresh Notification (Developer — 30 min)

Long-lived page tokens don't expire, but user tokens last 60 days. If a client's token dies:

• checkTokenHealth() already detects this and sets status: 'token_expired'
• Need to: show a "Reconnect Instagram" prompt on the client dashboard when status is expired
• Optional: send an email notification

6. Per-Client Data Structure

After a client connects Instagram, their record in iconic_clients.json gets an .instagram field:

{
  "[email protected]": {
    "name": "Neil Spence",
    "tier": "entry",
    "plan": "entry",
    "password": "...",
    "instagram": {
      "connected": true,
      "username": "iconicbyai",
      "igAccountId": "17841400000000",
      "pageId": "123456789",
      "accessToken": "EAA...long_page_token...",
      "connectedAt": "2026-04-04T12:00:00.000Z",
      "lastPostAt": null,
      "postCount": 0,
      "autoPost": false,
      "postsPerWeek": 3,
      "status": "active",
      "followers": 150,
      "profilePic": "https://..."
    }
  }
}

7. Posting Flow (How a Photo Gets to Instagram)

8. Live URLs

9. Environment & Tech Stack

• Runtime: Node.js v24.13.1
• Server: Raw Node HTTP (serve_reports.js, port 3100)
• Hosting: Render (auto-deploys on git push to master)
• Domain: reports.iconicbyai.com (Cloudflare tunnel)
• GitHub: NeilTheAussie/Studio1-Automation
• Client DB: iconic_clients.json + Supabase (jeneuarajdhwlqvmaqhj.supabase.co)
• Graph API: v22.0 via raw HTTPS (no SDK)
• OAuth scopes: instagram_basic, instagram_content_publish, pages_show_list, pages_read_engagement
• No npm dependencies — all Instagram code uses built-in Node https + fs modules

10. Testing Checklist

OAuth Flow

• Client at dashboard → clicks "Connect Instagram Account"
• Redirected to onboarding guide (or client setup page)
• After Meta App is configured: /api/instagram/connect redirects to Facebook
• User grants permissions → redirected back to dashboard
• Dashboard shows "Connected as @username"
• Token saved in iconic_clients.json

Single Image Posting

• POST /api/instagram/post-now with {email, photoFile, caption}
• Photo appears on client's Instagram feed within 2 minutes
• postCount incremented in iconic_clients.json
• lastPostAt updated

Scheduled Posting (after cron is added)

• Queue post via /api/instagram/admin/queue with future scheduledFor
• Post does NOT appear before scheduled time
• After time passes + cron fires → post appears
• Status in _schedule.json changes from "pending" to "posted"

Token Health

• POST /api/instagram/admin/check-health returns status for all clients
• Healthy tokens show {healthy: true}
• Expired tokens show {healthy: false, reason: "token_invalid"}