Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Integrating Instagram Graph API with AWS Lambda: Guest Photo Gallery Enhancement

What Was Done

We enabled Instagram media integration for the guest photo gallery system at shipcaptaincrew.queenofsandiego.com/g/{event_id}. Previously, the Lambda function had dormant Instagram integration that returned empty arrays due to missing environment variables. This post documents the technical walkthrough for connecting the Instagram Graph API, obtaining the necessary credentials, and deploying them to the Lambda function in AWS account 782785212866 (us-east-1 region).

The guest photo page system aggregates two content sources: user-uploaded charter photos stored in an approval queue, and @sailjada Instagram posts from matching time windows. By completing this integration, we unified the photo display without requiring manual curation.

Technical Details: Instagram Graph API Setup

Step 1: Add the Correct Product to Your App

The critical first step is adding the Instagram Graph API product to your Facebook app. This is distinct from Basic Display or Messaging APIs, which grant different scopes.

  • Navigate to developers.facebook.com/apps
  • Select the app sailjada-social
  • Click Add Product in the left sidebar
  • Search for and select Instagram Graph API
  • Confirm access type is set to Instagram Graph API (not Basic Display)

Why this matters: The Messaging use case (often the default suggestion) grants scopes for Direct Messages only. Reading media requires the instagram_basic scope, which is exclusive to the Graph API product. Selecting the wrong product prevents access to media endpoints.

Step 2: Verify Instagram Account Type and Page Linking

The @sailjada account must be a Business or Creator account, not a personal account. Additionally, it must be linked to a Facebook Page.

  • Log into @sailjada on Instagram and verify account type in Settings → Account → Account Type
  • Ensure the associated Facebook Page exists and is linked via Settings → Linked Accounts

Step 3: Connect the Instagram Account via App Dashboard

Inside the Instagram Graph API product settings, initiate the Instagram login flow:

  • Go to Instagram Graph API → API Setup with Instagram Login
  • Click Add Instagram Account
  • Authenticate as @sailjada
  • Grant the app permission to access the account

Step 4: Generate a Short-Lived Access Token

Use the Facebook Graph API Explorer to generate an initial token with the required scopes:

  • Navigate to developers.facebook.com/tools/explorer
  • In the top-left dropdown, select app sailjada-social
  • Click Generate Access Token
  • Select the Facebook Page linked to @sailjada
  • In the Permissions section, ensure these scopes are checked:
    • instagram_basic
    • pages_show_list
  • Click Generate

This token is short-lived (approximately 1 hour) and is used only to bootstrap the long-lived token process.

Step 5: Retrieve the Instagram User ID

Execute two Graph API calls using the short-lived token to obtain the Instagram Business Account ID:

curl -X GET "https://graph.instagram.com/v18.0/me/accounts?fields=instagram_business_account&access_token=YOUR_SHORT_LIVED_TOKEN"

From the response, extract the Facebook Page ID. Then use it in the second call:

curl -X GET "https://graph.instagram.com/v18.0/{PAGE_ID}?fields=instagram_business_account&access_token=YOUR_SHORT_LIVED_TOKEN"

The id field within the instagram_business_account object is your IG_USER_ID. Store this value securely.

Step 6: Exchange for a Long-Lived Token

The short-lived token is not suitable for Lambda environment variables. Exchange it for a long-lived token (valid for 60 days):

curl -X GET "https://graph.instagram.com/v18.0/oauth/access_token?grant_type=ig_refresh_token&access_token=YOUR_SHORT_LIVED_TOKEN"

The response includes a new access_token with an extended expiration. This is your IG_ACCESS_TOKEN.

Infrastructure: Lambda Configuration

The shipcaptaincrew Lambda function (us-east-1, account 782785212866) requires two environment variables to activate Instagram integration:

  • IG_USER_ID — The Instagram Business Account ID from Step 5
  • IG_ACCESS_TOKEN — The long-lived token from Step 6

Update the function configuration using the AWS CLI:

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

Security note: Store these values in AWS Secrets Manager rather than plaintext environment variables for production deployments. Update the Lambda execution role to include secretsmanager:GetSecretValue, and modify the function code to retrieve the secret on invocation.

Key Decisions and Rationale

  • Long-lived tokens over short-lived: Lambda is invoked on-demand for guest photo requests. Generating a new token per invocation adds latency and unnecessary API calls. A 60-day token reduces external dependencies while remaining manageable for rotation.
  • Graph API v18.0: Specified version in calls ensures compatibility across API updates. Meta deprecates older versions; hardcoding the version prevents unexpected breaking changes.
  • Business Account requirement: Only Business and Creator accounts have access to media insights and the Graph API. Personal accounts cannot be used, requiring @sailjada to have upgraded its account type beforehand.
  • Time window matching: The Lambda function filters Instagram posts by timestamp, comparing post creation time to the guest photo event date. This aggregation logic runs client-side or server-side; Graph API simply provides the raw media objects.

Verification and Testing

After deploying environment variables, test the integration:

  • Navigate to shipcaptaincrew.queenofsandiego.com/g/2026-04-29
  • The page should display both guest-uploaded photos and Instagram posts from 2026-04-29 in a unified gallery
  • CloudWatch Logs for the shipcaptaincrew function should show successful Graph API responses (no empty array fallback)

What's Next: Token Refresh Strategy