Instagram Integration

​

Overview

• Viewing your Instagram account information and insights
• Publishing posts directly from Fanfare
• Accessing recent media and engagement metrics
• Managing content for experience marketing

​

Prerequisites

• A Facebook Business Page
• An Instagram Business or Creator account linked to your Facebook Page
• Admin access to the Facebook Page

​

Account Requirements

1. Business or Creator account - Personal accounts are not supported
2. Connected to a Facebook Page - Required for the Instagram Graph API
3. Page admin access - You must be an admin of the connected Facebook Page

​

Setup

​

Step 1: Start the Connection Flow

1. Navigate to Settings > Integrations in Fanfare
2. Find Instagram and click to configure
3. Click Connect Instagram

​

Step 2: Authorize with Facebook

1. You’ll be redirected to Facebook’s OAuth flow
2. Log in to Facebook (if not already logged in)
3. Select the Facebook Page with the Instagram account you want to connect
4. Review and approve the requested permissions:
   • pages_show_list - View your Pages
   • pages_read_engagement - Read Page engagement data
   • instagram_basic - Access Instagram account info
   • instagram_manage_insights - View Instagram insights
   • instagram_content_publish - Publish content to Instagram
   • instagram_manage_comments - Manage Instagram comments
   • pages_manage_posts - Manage Page posts

​

Step 3: Verify Connection

• Your Instagram username
• Profile picture
• Follower count
• Media count

​

OAuth Flow

​

Authentication Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Fanfare   │────▶│  Facebook   │────▶│  Instagram  │
│   Admin     │     │   OAuth     │     │  Graph API  │
└─────────────┘     └─────────────┘     └─────────────┘
        │                   │
        │   Authorization   │
        │◀──────────────────│
        │                   │
        │   Access Token    │
        │◀──────────────────│
        │                   │
        ▼
┌─────────────┐
│  Long-lived │
│    Token    │
│   (60 days) │
└─────────────┘

​

Token Lifecycle

1. Short-lived token: Initial token valid for ~1 hour
2. Long-lived token: Exchanged for 60-day token
3. Token refresh: Automatically refreshed before expiration

​

Token Storage

​

Features

​

View Account Information

GET /api/instagram/account

{
  "id": "17841234567890",
  "username": "mybrand",
  "name": "My Brand",
  "profile_picture_url": "https://...",
  "followers_count": 10500,
  "media_count": 245
}

​

Get Recent Media

GET /api/instagram/media

[
  {
    "id": "17891234567890",
    "caption": "Check out our new product! #launch",
    "media_type": "IMAGE",
    "media_url": "https://...",
    "timestamp": "2024-06-20T14:30:00Z",
    "permalink": "https://instagram.com/p/ABC123",
    "like_count": 234,
    "comments_count": 45
  }
]

​

Get Account Insights

GET /api/instagram/insights

{
  "impressions": 25000,
  "reach": 18000,
  "profile_views": 1200,
  "website_clicks": 450,
  "follower_count": 10500
}

​

Create a Post

POST /api/instagram/posts
Content-Type: application/json

{
  "imageUrl": "https://example.com/product-image.jpg",
  "caption": "Exciting new drop coming soon! 🎉 #launch #exclusive"
}

{
  "mediaId": "17891234567891",
  "permalink": "https://instagram.com/p/XYZ789"
}

​

Disconnecting

1. Navigate to Settings > Integrations
2. Click on the Instagram integration
3. Click Disconnect

DELETE /api/instagram/disconnect

{
  "success": true,
  "message": "Instagram account disconnected successfully"
}

​

What Happens When You Disconnect

• Access token is removed
• No further API calls can be made
• Historical data remains in logs
• You can reconnect at any time

​

API Reference

​

Get Authorization URL

GET /api/instagram/auth/url

​

OAuth Callback

GET /api/instagram/auth/callback?code=XXX&state=ORG_ID

​

Get Connected Account

GET /api/instagram/account

​

Get Recent Media

GET /api/instagram/media

​

Get Account Insights

GET /api/instagram/insights

​

Create Post

POST /api/instagram/posts

​

Disconnect Account

DELETE /api/instagram/disconnect

​

Token Refresh

​

Automatic Refresh

• An API call is made
• Token is expiring within 5 days
• Refresh happens transparently

​

Manual Token Check

​

Troubleshooting

​

Common Issues

• Go to your Facebook Page settings
• Connect an Instagram Business or Creator account
• Ensure you’re selecting the correct Facebook Page

• Ensure you’re logged into the correct Facebook account
• Check that you have admin access to the Facebook Page
• Try clearing browser cache and cookies

• Token may have been revoked
• Disconnect and reconnect the integration
• Check that the Facebook App is still authorized

• Verify image URL is publicly accessible
• Check image format and size requirements
• Ensure instagram_content_publish permission was granted

​

Checking Connection Status

curl -X GET /api/instagram/account \
  -H "Authorization: Bearer YOUR_TOKEN"

​

Security

​

Data Handling

• Access tokens encrypted at rest
• Tokens never exposed in client-side code
• Facebook Page access limited to authorized users

​

Permission Scopes

​

Token Security

• Long-lived tokens (60 days) used for extended access
• Tokens refreshed automatically
• Tokens revocable from Facebook Settings

​

Limitations

​

Future Enhancements

​

Related Resources

• Marketing Automation
• Instagram Graph API Documentation
• Facebook Developer Portal