Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

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

What Was Done

We enabled Instagram media integration for the guest photo gallery system at shipcaptaincrew.queenofsandwick.com/g/{event_id} by connecting the existing but dormant Instagram integration in the Lambda function to the Instagram Graph API. The Lambda function (shipcaptaincrew, running in us-east-1, account 782785212866) previously returned an empty array when IG_USER_ID and IG_ACCESS_TOKEN environment variables were missing. This walkthrough covers the process of obtaining those credentials and activating the integration.

Technical Details: Instagram Graph API Setup

Step 1: Adding the Correct Product to Your Facebook App

The initial setup required careful product selection. The sailjada-social app on developers.facebook.com already had a Messaging product configured, but this product grants scopes for direct messaging, not media reading. The key insight here is that Instagram's Graph API has distinct products for different use cases:

  • Basic Display API — read-only access to profile info and media (simpler, more limited)
  • Graph API with Messaging — designed for inbox and conversation access (not suitable for our use case)
  • Instagram Graph API — full media, insights, and business account capabilities (what we needed)

Process:

  1. Navigate to developers.facebook.com/apps and open the sailjada-social app
  2. In the left sidebar, locate and click Add Product (positioned near the bottom of the navigation menu)
  3. Search for "Instagram" in the product catalog
  4. Select Instagram Graph API and click "Set Up"
  5. Confirm the access type as Instagram Graph API when prompted

Step 2: Account Prerequisites

Before proceeding with token generation, the @sailjada Instagram account must meet specific requirements:

  • Must be a Business or Creator account (not a personal account)
  • Must be linked to a Facebook Page that the app has permission to manage
  • The app user (in this case, the developer account) must have admin or editor access to that Facebook Page

Connecting the account: Inside the Instagram Graph API product page, navigate to API setup with Instagram login and click Add Instagram account. Log in as @sailjada and authorize the app to access the account's media and insights data.

Step 3: Short-Lived Access Token Generation

Instagram Graph API uses a two-tier token system. Short-lived tokens (valid for about 1 hour) are exchanged for long-lived tokens (valid for 60 days). The short-lived token is generated through the Graph API Explorer:

  1. Open developers.facebook.com/tools/explorer
  2. In the top-right app selector, choose sailjada-social
  3. Click the "Generate Access Token" button
  4. When prompted to select a user or page, choose the Facebook Page linked to @sailjada
  5. In the "User or Page" dropdown, confirm the correct page is selected
  6. Under "Permissions," ensure the following scopes are checked:
    • instagram_basic — required to read media, profile info, and account details
    • pages_show_list — required to list pages managed by the app user
  7. Click "Generate" to create the token

Copy the generated token and save it temporarily—you'll use it in the next step.

Step 4: Retrieving the Instagram User ID

The Instagram User ID (IG_USER_ID) is a numeric identifier specific to the @sailjada business account. It's retrieved via two API calls. First, get the Facebook Page ID:

curl -X GET "https://graph.instagram.com/v18.0/me/accounts?access_token=TOKEN"

The response will include a facebook_page_id field. Use this in the second call:

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

The response will contain an instagram_business_account object with an id field—this is your IG_USER_ID. Store this value.

Step 5: Exchanging for a Long-Lived Token

Short-lived tokens expire quickly. Exchange your short-lived token for a long-lived token (60-day expiry) using your app credentials:

curl -X GET "https://graph.instagram.com/v18.0/access_token" \
  -d "grant_type=ig_refresh_token" \
  -d "access_token=SHORT_LIVED_TOKEN"

The returned access_token value is your IG_ACCESS_TOKEN. This token is suitable for storage in Lambda environment variables because it's valid for 60 days and can be refreshed using the same call.

Infrastructure: Lambda Configuration

Once you have both IG_USER_ID and IG_ACCESS_TOKEN, update the Lambda function's environment variables:

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

The Lambda function checks for these environment variables at invocation time. When both are present and valid, it queries the Instagram Graph API endpoint:

https://graph.instagram.com/v18.0/{IG_USER_ID}/media?fields=id,caption,media_type,media_url,timestamp&access_token={IG_ACCESS_TOKEN}

The returned media objects are filtered by timestamp to match the event date window and merged with guest-uploaded photos in the response payload.

Key Architectural Decisions

  • Long-lived tokens over short-lived: Lambda functions should not perform OAuth flows at runtime. Storing a 60-day token in environment variables eliminates the need for token refresh logic during request handling, reducing latency and complexity.
  • Environment variables over Secrets Manager: Since the long-lived token has a known expiry (60 days), we opted for environment variables rather than AWS Secrets Manager. This simplifies deployment while adding a built-in refresh requirement.
  • API call at request time: Rather than caching Instagram media in DynamoDB, the Lambda function calls the Instagram Graph API on each guest page request. This ensures gallery content stays current with the latest @sailjada posts, though it introduces a small latency cost and API rate-limit considerations.

What's Next