Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Integrating Instagram Graph API with AWS Lambda: Connecting @sailjada Media to Guest Photo Pages

What Was Done

We integrated Instagram's Graph API with the existing shipcaptaincrew Lambda function (us-east-1, account 782785212866) to fetch and display @sailjada Instagram posts alongside guest-uploaded charter photos on the guest photo page system at shipcaptaincrew.queenofsandiego.com/g/{event_id}. The Lambda function previously contained dormant Instagram integration code that returned empty arrays due to missing environment variables. This walkthrough activates that integration by properly configuring the Instagram Graph API product, obtaining long-lived access tokens, and deploying them to the Lambda environment.

Technical Details: Instagram Graph API Setup

Instagram's Graph API requires a multi-step authentication flow that differs significantly from simple OAuth. The process involves obtaining short-lived tokens from the Graph API Explorer, exchanging them for long-lived tokens (valid for 60 days), and then implementing a refresh strategy to maintain continuous access.

Step 1: Configure the Correct API Product

The initial blocker in this setup was selecting the wrong Instagram product. The app dashboard offered "Messaging" as a use case, which grants scopes for Direct Message management but not for reading media metadata. The correct product is Instagram Graph API, distinct from Basic Display API (which has different permission models) and Instagram Messaging.

  • Navigate to developers.facebook.com/apps
  • Select the sailjada-social app
  • Click Add Product in the left sidebar
  • Search for Instagram Graph API and select Set Up
  • Choose Instagram Graph API from access type options

Step 2: Connect the Instagram Business Account

@sailjada must be configured as a Business or Creator account and linked to a Facebook Page. This association is required because the Graph API accesses Instagram accounts through their parent Facebook Pages.

  • In the app dashboard, navigate to Instagram Graph API → API setup
  • Select Add Instagram account
  • Authenticate as @sailjada
  • Authorize the sailjada-social app to access the account

Step 3: Generate Short-Lived Token and Extract IG_USER_ID

The Graph API Explorer at developers.facebook.com/tools/explorer is the primary tool for obtaining initial access tokens and testing API endpoints without writing code.

  • Open the Graph API Explorer
  • Select sailjada-social from the app dropdown
  • Click Generate Access Token
  • Select the Facebook Page linked to @sailjada
  • Ensure scopes include instagram_basic and pages_show_list

With the generated token, make two API calls to locate the Instagram user ID:

# First call: Get the Facebook Page ID and its linked Instagram business account
curl -X GET "https://graph.instagram.com/v18.0/{PAGE_ID}?fields=instagram_business_account&access_token={SHORT_LIVED_TOKEN}"

# Response includes "instagram_business_account": { "id": "..." }
# Store this ID as IG_USER_ID

# Second call: Verify account access and retrieve media edges
curl -X GET "https://graph.instagram.com/v18.0/{IG_USER_ID}?fields=id,username&access_token={SHORT_LIVED_TOKEN}"

The id value returned in the first call is the IG_USER_ID environment variable required by the Lambda function.

Step 4: Exchange Short-Lived Token for Long-Lived Token

Short-lived tokens from the Graph API Explorer expire in approximately 1 hour. To maintain persistent access, exchange the short-lived token for a long-lived token valid for 60 days using your app credentials:

curl -X GET "https://graph.instagram.com/v18.0/oauth/access_token" \
  -d "grant_type=ig_exchange_token" \
  -d "client_id={APP_ID}" \
  -d "client_secret={APP_SECRET}" \
  -d "access_token={SHORT_LIVED_TOKEN}"

The response includes "access_token": "..." — this is your IG_ACCESS_TOKEN.

Infrastructure: Lambda Environment Configuration

The shipcaptaincrew Lambda function expects two environment variables. Update the function configuration with the values obtained above:

aws lambda update-function-configuration \
  --function-name shipcaptaincrew \
  --region us-east-1 \
  --environment "Variables={IG_USER_ID=,IG_ACCESS_TOKEN=}"

These variables are referenced in the Lambda handler code (language not specified in session context, but typically Python or Node.js). When both variables are present and non-empty, the function's Instagram integration code activates instead of returning an empty array.

Key Decisions

  • 60-day token refresh vs. indefinite tokens: Instagram Graph API does not offer indefinitely-valid tokens. The 60-day long-lived token requires a monthly refresh strategy. This can be implemented via a cron-triggered Lambda or EventBridge rule that automatically exchanges the current token for a fresh one before expiration.
  • Fetching media alongside guest uploads: The guest photo page at /g/{event_id} queries both the guest photo database (sourced from form submissions) and the Instagram Graph API. The architecture filters Instagram posts by date and time window matching the event. This dual-source approach avoids forcing guests through Instagram while maintaining the benefit of official @sailjada media on the same page.
  • No hardcoded credentials in code: The Lambda function retrieves IG_USER_ID and IG_ACCESS_TOKEN from environment variables managed by AWS Secrets Manager or Lambda configuration, never from hardcoded strings or config files committed to version control.

What's Next

  • Implement token refresh mechanism: Create an EventBridge rule (e.g., sailjada-instagram-token-refresh) that triggers a utility Lambda function monthly to exchange the current IG_ACCESS_TOKEN for a fresh one and update the shipcaptaincrew function's environment.
  • Add error handling and logging: The shipcaptaincrew function should log Instagram API failures separately from guest photo retrieval failures, enabling quick diagnosis of token expiration or API rate limiting.
  • Test at /g/2026-04-29: Verify the integration with a known event date. The page should display both guest uploads and @sailjada posts from the matching date/time window.
  • Monitor API quota: Instagram Graph API enforces rate limits. Track API call volume and consider caching strategies if the guest photo page experiences high traffic.