Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

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

Overview

The guest photo page system at shipcaptaincrew.queenofsandiego.com/g/{event_id} displays approved guest-uploaded charter photos alongside Instagram posts from @sailjada. While the Lambda function had dormant Instagram integration code, the actual API credentials were missing. This post covers the complete setup process to activate Instagram Graph API integration, including token generation, exchange flow, and Lambda environment variable configuration.

What Was Done

We activated Instagram Graph API integration for the shipcaptaincrew Lambda function (us-east-1, account 782785212866) by:

  • Adding the Instagram Graph API product to the existing sailjada-social Facebook app
  • Obtaining short-lived and long-lived access tokens via the Graph API Explorer
  • Retrieving the Instagram business account ID for @sailjada
  • Configuring Lambda environment variables with the tokens
  • Implementing a token refresh strategy for 60-day token rotation

Technical Details: The Instagram Graph API Setup Flow

Step 1: Adding the Correct Product to Your App

The sailjada-social app had a Messaging product added previously, which provides DM capabilities but does not grant the instagram_basic scope required to read media. The correct product is Instagram Graph API (distinct from Basic Display and Messaging).

Process:

  • Navigate to developers.facebook.com/apps
  • Select the sailjada-social application
  • In the left sidebar, click Add Product (near the bottom of the sidebar)
  • Search for and select Instagram Graph API
  • Choose Instagram Graph API as the access type (not Basic Display)

The Graph API product will now appear in your app's left sidebar under Products.

Step 2: Linking the @sailjada Instagram Account

Before tokens can be generated, the @sailjada Instagram account must be connected as a Business or Creator account linked to a Facebook Page. @sailjada must have the appropriate role (Admin or Analyst) on both the Instagram account and its linked Facebook Page.

Connection process:

  • Inside the Instagram Graph API product settings, navigate to API Setup
  • Click Add Instagram Account
  • Authenticate with @sailjada credentials (or the account admin)
  • Authorize the app to access the Instagram business account

Step 3: Generating a Short-Lived Access Token

The Graph API Explorer is the quickest way to generate and test tokens. This token has a lifespan of approximately 1 hour and is used to obtain a long-lived token (60 days).

Steps:

  • Open developers.facebook.com/tools/explorer
  • In the top-left dropdown, select sailjada-social as the app
  • Click Generate Access Token
  • Select the Facebook Page linked to @sailjada
  • Under Scopes, ensure instagram_basic and pages_show_list are selected
  • The token appears in the Access Token field at the top

Step 4: Retrieving the Instagram Business Account ID

With the short-lived token in hand, two API calls retrieve the Instagram business account ID (referred to as IG_USER_ID in Lambda environment variables).

Call 1 — Get Page ID:

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

This returns your Facebook Page ID. Note the instagram_business_account.id field from the response — this is your IG_USER_ID.

Step 5: Exchanging Short-Lived Token for Long-Lived Token

The short-lived token (1 hour) must be exchanged for a long-lived token (60 days) suitable for server-side Lambda execution.

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

The response contains an access_token field with a 60-day lifespan. This is your IG_ACCESS_TOKEN.

Infrastructure: Lambda Configuration

The shipcaptaincrew Lambda function (us-east-1) uses environment variables to store Instagram credentials. The existing code checks for IG_USER_ID and IG_ACCESS_TOKEN and returns an empty array if either is missing.

Update Lambda environment variables:

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

No code changes are required — the Lambda function's existing Instagram integration will activate once these variables are populated.

Key Decisions and Rationale

  • Instagram Graph API over Basic Display: Graph API provides both media metadata and insights. Basic Display is read-only and lacks scopes needed for filtering by date ranges.
  • 60-day long-lived tokens vs. indefinite tokens: Long-lived tokens balance security and operational simplicity. A monthly refresh via the same token exchange call (or EventBridge automation) keeps tokens fresh without manual intervention.
  • Environment variables vs. Secrets Manager: While Secrets Manager offers better audit trails and rotation, environment variables are sufficient here since tokens are non-human credentials and the Lambda function is private (no public endpoint).
  • No code changes to Lambda: The dormant integration code was production-ready; we only supplied credentials. This minimizes deployment risk.

Token Refresh Strategy

The long-lived token expires after 60 days. To maintain service continuity:

  • Manual refresh: Run the token exchange curl call monthly and update Lambda environment variables via the AWS CLI command above.
  • Automated refresh (optional): Use EventBridge to trigger a Lambda function monthly that calls the token exchange endpoint and updates the shipcaptaincrew function's environment variables via the AWS Lambda API.

Verification

Once Lambda is configured, visit shipcaptaincrew.queenofsandiego.com