# Facebook Graph API

Monitor your Facebook pages, posts, engagement metrics, and personal activity with AI-powered insights into your social media presence.

Connect Weavestream to Facebook to monitor:

For Personal Profiles:

• 📝 Your Posts - Your personal timeline posts
• 📸 Your Photos - Photos you've uploaded
• 👍 Your Likes - Pages and content you've liked
• 👥 Your Friends - Friend list (limited by privacy)

For Pages You Manage:

• 📄 Page Posts - All posts from your Facebook page
• 💬 Post Engagement - Likes, comments, shares on posts
• 📊 Page Insights - Reach, impressions, engagement metrics
• 📅 Scheduled Posts - Posts scheduled for future publication
• 💬 Comments - Comments on your page posts
• ⭐ Reviews - Reviews left on your page (if applicable)
• 📨 Messages - Page inbox messages (with appropriate permissions)

Estimated Setup Time: 15-20 minutes

Facebook Graph API has significant restrictions:

• ✅ Read your own posts, photos, likes
• ❌ Cannot read friends' posts or timelines
• ❌ Cannot read most personal profile data of others
• ❌ Very limited analytics

• ✅ Full control over page content
• ✅ Detailed analytics and insights
• ✅ All engagement metrics
• ✅ Scheduling and management features
• ✅ This is the recommended use case for Weavestream

Recommendation: Focus on Page monitoring for business/brand use. Personal profile access is very limited.

• Facebook account
• Facebook Page (for full functionality)
• Page admin access (for page monitoring)
• Weavestream installed on your Mac

1. Go to https://developers.facebook.com
2. Sign in with your Facebook account
3. Click "My Apps" (top right)
4. Click "Create App"

Select app type based on your use case:

For Page Monitoring (Recommended):

• Select "Business" or "Other"

For Personal Profile (Limited):

• Select "Consumer" or "Other"

Click "Next"

Display Name:

Weavestream Monitor

App Contact Email:

your-email@example.com

App Purpose:

• Select "Yourself or your own business"

Click "Create App"

1. On your app dashboard, find "Facebook Login"
2. Click "Set Up" on Facebook Login
3. Select "Web" as platform
4. Site URL: http://localhost:8080
5. Click "Save"

1. In left sidebar, click "Facebook Login" → "Settings"
2. Under "Valid OAuth Redirect URIs", add:

   http://localhost:8080/callback

3. Click "Save Changes"

1. In left sidebar, click "App Review" → "Permissions and Features"
2. Request these permissions (click "Request Advanced Access"):

For Personal Profile:

• user_posts - Read your posts
• user_photos - Read your photos
• user_likes - Read pages you've liked

For Page Monitoring (Recommended):

• pages_show_list - List pages you manage
• pages_read_engagement - Read page content and engagement
• pages_read_user_content - Read user-generated content on your page
• pages_manage_posts - Manage page posts
• read_insights - Read page insights/analytics
• pages_messaging - Read page messages (optional)

3. Click "Get Advanced Access" for each permission
4. Some may require app review by Facebook (can take days)

Option 1: Graph API Explorer (Quick Testing)

1. Go to https://developers.facebook.com/tools/explorer
2. Select your app from dropdown
3. Click "Generate Access Token"
4. Select permissions you need
5. Click "Generate Access Token"
6. Copy the token

⚠️ Warning: This token expires in 1-2 hours. For production use, implement OAuth flow.

Option 2: Get Long-Lived Token (Recommended)

After getting short-lived token from Graph API Explorer:

1. Go to: https://developers.facebook.com/tools/debug/accesstoken
2. Paste your token
3. Click "Debug"
4. Click "Extend Access Token"
5. Copy the new long-lived token (valid for 60 days)

For Page Tokens: Get page access token after user access token:

GET https://graph.facebook.com/v24.0/me/accounts?access_token=USER_TOKEN

This returns page tokens that don't expire (as long as you remain page admin).

Option 3: OAuth Flow (Production)

For production use with auto-refresh (see Advanced section).

If monitoring a page:

Method 1: Via Page Settings

1. Go to your Facebook page
2. Click "Settings"
3. Look for "Page ID" in the left sidebar or general settings

Method 2: Via Graph API

GET https://graph.facebook.com/v24.0/me/accounts?access_token=YOUR_TOKEN

Returns all pages you manage with their IDs.

Method 3: Via Page URL

1. Go to your page
2. Look at URL: facebook.com/YourPageName
3. Use Graph API:

GET https://graph.facebook.com/v24.0/YourPageName?access_token=YOUR_TOKEN

Response includes page ID.

1. Open Weavestream
2. Click the "+" button in the sidebar
3. Select "Add Source"
4. Fill in the source details:
   • Name: Facebook (or Facebook - [Page Name])
   • Base URL: https://graph.facebook.com/v24.0
   • Auth Type: Query Parameter
   • Query Param Name: access_token
   • Query Param Value: Paste your access token
   • Icon: Select person.circle or custom facebook icon if available
   • Color: Choose your preference (suggested: #1877F2 - Facebook blue, or #007AFF)
   • Refresh Interval: 60 minutes (1 hour)
5. Click "Add" or "Save"

Get your personal timeline posts.

Configuration:

• Name: My Posts
• Path: /me/posts
• Method: GET

Query Parameters:

• fields: id,message,created_time,story,full_picture,type,link

Field Mapping:

• Array Path: data
• ID Field: id
• Title Field: story (or compute from message preview)
• Date Field: created_time
• Summary Fields: message, type, link
• Status Field: (none)

Retention Mode: Keep All

Get photos you've uploaded.

Configuration:

• Name: My Photos
• Path: /me/photos
• Method: GET

Query Parameters:

• fields: id,name,created_time,from,picture,images
• type: uploaded (only photos you uploaded, not tagged in)

Field Mapping:

• Array Path: data
• ID Field: id
• Title Field: from.name (your name)
• Date Field: created_time
• Summary Fields: name, picture
• Status Field: (none)

Retention Mode: Archive on Sync

Get pages you've liked (limited info).

Configuration:

• Name: Liked Pages
• Path: /me/likes
• Method: GET

Query Parameters:

• fields: id,name,category,link

Field Mapping:

• Array Path: data
• ID Field: id
• Title Field: name
• Date Field: (none available)
• Summary Fields: category, link

Get all posts from your Facebook page.

Configuration:

• Name: Page Posts
• Path: /{PAGE_ID}/posts

Replace {PAGE_ID} with your actual page ID

Example: /123456789012345/posts

Query Parameters:

• fields: id,message,created_time,story,full_picture,type,permalink_url,reactions.summary(true),comments.summary(true),shares
• limit: 100

Field Mapping:

• Array Path: data
• ID Field: id
• Title Field: Compute from message (first 50 chars) or use story
• Date Field: created_time
• Summary Fields: message, type, reactions.summary.total_count, comments.summary.total_count, shares.count
• Status Field: (none)

Retention Mode: Keep All

Alternative simpler endpoint.

Configuration:

• Name: Published Posts
• Path: /{PAGE_ID}/published_posts
• Method: GET

Query Parameters:

• fields: id,message,created_time,full_picture,permalink_url
• limit: 50

Field Mapping: Same as Page Posts

Get page performance metrics.

Configuration:

• Name: Page Insights
• Path: /{PAGE_ID}/insights
• Method: GET

Query Parameters:

• metric: page_impressions,page_reach,page_engaged_users,page_post_engagements
• period: day (or week, days_28)
• since: 2024-01-01 (start date)
• until: 2024-01-31 (end date)

Field Mapping:

• Array Path: data
• ID Field: id
• Title Field: name (metric name)
• Date Field: Use sync time or parse from values
• Summary Fields: values, description

Note: Insights data structure is complex. You may need custom parsing.

Get detailed engagement for a specific post.

Configuration:

• Name: Post Engagement - [Post ID]
• Path: /{POST_ID}
• Method: GET

Replace {POST_ID} with actual post ID

Query Parameters:

• fields: id,message,created_time,reactions.summary(true),comments.summary(true),shares,insights.metric(post_impressions,post_engaged_users)

Field Mapping:

• ID Field: id
• Title Field: message (preview)
• Date Field: created_time
• Summary Fields: All engagement metrics

Use Case: Create separate endpoints for important posts to track detailed metrics.

Get reviews left on your page (if applicable - restaurants, businesses).

Configuration:

• Name: Page Reviews
• Path: /{PAGE_ID}/ratings
• Method: GET

Query Parameters:

• fields: created_time,reviewer,rating,review_text

Field Mapping:

• Array Path: data
• ID Field: id
• Title Field: reviewer.name
• Date Field: created_time
• Summary Fields: rating, review_text
• Status Field: rating
  • Map 5 → ok
  • Map 4 → info
  • Map 1-3 → warning

Get all comments on your page's posts.

Configuration:

• Name: Page Comments
• Path: /{PAGE_ID}/conversations
• Method: GET

Or for specific post:

• Path: /{POST_ID}/comments

Query Parameters:

• fields: id,created_time,from,message,comment_count,like_count
• filter: stream (all comments)

Field Mapping:

• Array Path: data
• ID Field: id
• Title Field: from.name
• Date Field: created_time
• Summary Fields: message, like_count, comment_count

Get posts scheduled for future publication.

Configuration:

• Name: Scheduled Posts
• Path: /{PAGE_ID}/scheduled_posts
• Method: GET

Query Parameters:

• fields: id,message,created_time,scheduled_publish_time

Field Mapping:

• Array Path: data
• ID Field: id
• Title Field: message (preview)
• Date Field: scheduled_publish_time
• Summary Fields: message, created_time

Get messages sent to your page inbox.

Configuration:

• Name: Page Messages
• Path: /{PAGE_ID}/conversations
• Method: GET

Query Parameters:

• fields: id,updated_time,messages{message,from,created_time}

Requires: pages_messaging permission

Field Mapping:

• Array Path: data
• Complex nested structure - may need custom parsing

Note: Messages API is complex. Consider using for urgent message monitoring only.

{
  "data": [
    {
      "id": "123456789_987654321",
      "message": "Check out our new product!",
      "created_time": "2024-01-26T14:30:00+0000",
      "story": "Company Name shared a link.",
      "full_picture": "https://scontent.xx.fbcdn.net/...",
      "type": "link",
      "permalink_url": "https://facebook.com/...",
      "reactions": {
        "summary": {
          "total_count": 150
        }
      },
      "comments": {
        "summary": {
          "total_count": 25
        }
      },
      "shares": {
        "count": 10
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "abc123",
      "after": "xyz789"
    },
    "next": "https://graph.facebook.com/..."
  }
}

Key Fields:

• id - Unique post identifier
• message - Post text content
• created_time - ISO 8601 timestamp
• reactions.summary.total_count - Total likes/reactions
• comments.summary.total_count - Number of comments
• shares.count - Number of shares
• permalink_url - Direct link to post

{
  "data": [
    {
      "name": "page_impressions",
      "period": "day",
      "values": [
        {
          "value": 1250,
          "end_time": "2024-01-26T08:00:00+0000"
        }
      ],
      "title": "Daily Total Impressions",
      "description": "Daily: The number of times any content from your Page or about your Page entered a person's screen."
    }
  ]
}

1. Under Facebook source, click "+" → "New Filter"
2. Name: Posts This Week
3. Select Endpoint: Page Posts or My Posts
4. Add Condition:
   • Field: created_time
   • Operator: in last
   • Value: 7 days
5. Save

1. Create new filter
2. Name: High Engagement (100+ reactions)
3. Select Endpoint: Page Posts
4. Add Condition:
   • Field: reactions.summary.total_count
   • Type: Number
   • Operator: greater than
   • Value: 100
5. Save

1. Create new filter
2. Name: Posts with Comments
3. Select Endpoint: Page Posts
4. Add Condition:
   • Field: comments.summary.total_count
   • Type: Number
   • Operator: greater than
   • Value: 0
5. Save

1. Create new filter
2. Name: Video Posts
3. Select Endpoint: Page Posts
4. Add Condition:
   • Field: type
   • Operator: equals
   • Value: video
5. Save

Post Types:

• link - Shared links
• status - Text-only posts
• photo - Photos
• video - Videos
• offer - Offers/promotions

1. Create new filter
2. Name: Low Engagement (<10 reactions)
3. Select Endpoint: Page Posts
4. Add Conditions:
   • Field: reactions.summary.total_count
   • Operator: less than
   • Value: 10
   • AND
   • Field: created_time
   • Operator: in last
   • Value: 7 days
5. Save

Engagement Analysis:

• "What posts got the most engagement this week?"
• "Show me posts with over 100 likes"
• "What's my average engagement rate?"
• "Which posts had the most comments?"

Content Performance:

• "What type of content performs best? (video vs photo vs link)"
• "When do I get the most engagement?"
• "What topics resonate with my audience?"
• "Show me underperforming posts"

Trend Analysis:

• "How is my engagement trending over time?"
• "Compare this month's performance to last month"
• "What was my most viral post?"
• "Show me engagement by day of week"

Content Planning:

• "What should I post about next based on past performance?"
• "Find successful post templates I can reuse"
• "What hashtags/topics should I focus on?"

Community Management:

• "Show me posts that need responses"
• "Which posts have unanswered comments?"
• "What negative reviews need attention?"

Page Management:

• "Summarize my page's performance this month"
• "What scheduled posts are upcoming?"
• "Show me inbox messages I haven't responded to"

Facebook uses cursor-based pagination:

Response includes:

{
  "paging": {
    "cursors": {
      "before": "abc123",
      "after": "xyz789"
    },
    "next": "https://graph.facebook.com/v24.0/..."
  }
}

To get next page: Use the next URL or add after=xyz789 cursor to your request.

Weavestream should handle this automatically.

Facebook Graph API uses field expansion:

Basic request:

GET /{PAGE_ID}/posts

Returns minimal fields.

With field selection:

GET /{PAGE_ID}/posts?fields=id,message,created_time,reactions.summary(true)

Returns only specified fields.

Nested field expansion:

fields=id,from{name,picture},comments{message,from}

Benefits:

• Faster responses
• Less data transfer
• Get exactly what you need

Available page insights metrics:

Engagement:

• page_engaged_users - People who engaged
• page_post_engagements - Total engagements
• page_consumptions - Content clicks
• page_negative_feedback - Hide/unlike/report actions

Reach:

• page_impressions - Times content was viewed
• page_impressions_unique - Unique viewers
• page_reach - People reached
• page_impressions_organic - Non-paid impressions

Page Views:

• page_views_total - Total page views
• page_views_external_referrals - From outside Facebook

Actions:

• page_actions_post_reactions_total - Reactions on posts
• page_fan_adds - New page likes
• page_fan_removes - Page unlikes

Period options: day, week, days_28, lifetime

For production use with auto-refreshing tokens:

1. Authorization URL:

https://www.facebook.com/v24.0/dialog/oauth?client_id=YOUR_APP_ID&redirect_uri=http://localhost:8080/callback&scope=pages_show_list,pages_read_engagement,read_insights

2. Token URL:

https://graph.facebook.com/v24.0/oauth/access_token

3. Required Parameters:

   • client_id: Your app ID
   • client_secret: Your app secret
   • redirect_uri: http://localhost:8080/callback
   • code: Authorization code from redirect
   • grant_type: authorization_code

4. Get Long-Lived Token:

GET /oauth/access_token?grant_type=fb_exchange_token&client_id=APP_ID&client_secret=APP_SECRET&fb_exchange_token=SHORT_TOKEN

5. Get Page Token (Never Expires):

GET /me/accounts?access_token=USER_TOKEN

Solution:

1. Token expired - get a new long-lived token
2. Verify token is for the correct app
3. Check permissions haven't been revoked
4. Debug token at: https://developers.facebook.com/tools/debug/accesstoken

Solution:

1. Go to Graph API Explorer
2. Click "Get User Access Token"
3. Select the required permission
4. Generate new token with that permission
5. For production: Request permission in App Review

Solution:

1. Verify endpoint path is correct (starts with /)
2. Check you're using correct version (v24.0)
3. Ensure you have permission for that endpoint
4. Some endpoints require page tokens, not user tokens

Solution: Most Facebook endpoints return data in data array. Ensure:

1. Array path is set to data
2. Response is actually an array (some insights return objects)
3. Token has permission to access that data

Solution: Facebook has rate limits per app and per user:

• App-level: ~200 calls/hour/user
• Page-level: Higher limits for pages

Best practices:

• Increase refresh interval (60+ minutes)
• Use field selection to reduce data transfer
• Don't poll frequently for real-time updates
• Consider webhooks for real-time notifications (advanced)

Solution: This is intentional. Facebook Graph API doesn't allow reading friends' posts for privacy reasons. You can only:

• Read your own posts
• Read posts on pages you manage
• Read public posts you're tagged in (limited)

Page Access Tokens:

• Don't expire (as long as you remain admin)
• More secure than user tokens
• Recommended for production

User Access Tokens:

• Short-lived: 1-2 hours
• Long-lived: 60 days
• Need to be refreshed

Best Practices:

• Never share tokens publicly
• Use page tokens when possible
• Rotate tokens regularly
• Store securely (Weavestream uses macOS Keychain)
• Monitor token usage in app dashboard

For Personal Profiles:

• Only your own data is accessible
• Privacy settings affect what you can access
• Friends' data is protected

For Pages:

• All published content is accessible via API
• Unpublished/draft content requires manage permissions
• Private messages require special permissions and app review

Before you finish, verify:

• ✅ Facebook app created in Developers portal
• ✅ Required permissions requested/approved
• ✅ Access token obtained (long-lived or page token)
• ✅ Page ID found (if monitoring pages)
• ✅ Facebook source added to Weavestream
• ✅ At least one endpoint configured (Posts or Page Posts)
• ✅ Array path set to data
• ✅ Field mappings working (post content and dates visible)
• ✅ Smart filters created for engagement analysis
• ✅ Tested AI questions about your Facebook data

You're all set! Analyze your social media presence with AI-powered insights! 📱

Last updated: February 2026 Facebook Graph API version: v24.0