Facebook Pages API — SKILL.md

---
name: "Facebook Pages API"
description: "Skill for Facebook Pages API — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "social"
agents: ["claude-code", "codex", "gemini"]
tags: ["facebook-api", "social", "auto-generated"]
---

# Facebook Pages API

---
name: Facebook Pages API
description: Use when you need to manage Facebook Pages programmatically - posting content, retrieving insights, managing page information, or building social media management tools
metadata:
  author: skynet
  version: 1.0.0
category: social
---

# Facebook Pages API

## Prerequisites

```bash
# Install Facebook SDK (choose your language)
npm install facebook-nodejs-business-sdk  # Node.js
pip install facebook-business              # Python
composer require facebook/graph-sdk        # PHP
```

## Authentication Setup

```bash
# Get your access token (replace with actual values)
export FB_ACCESS_TOKEN="your_page_access_token"
export FB_PAGE_ID="your_page_id"
export FB_APP_ID="your_app_id"
export FB_APP_SECRET="your_app_secret"

# Test authentication
curl -X GET "https://graph.facebook.com/v18.0/me/accounts?access_token=$FB_ACCESS_TOKEN"
```

## Basic Page Information

```bash
# Get page details
curl -X GET \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID?fields=name,about,category,link,phone,website,fan_count&access_token=$FB_ACCESS_TOKEN"

# Get page insights (requires Page Insights permission)
curl -X GET \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/insights?metric=page_fans,page_impressions&access_token=$FB_ACCESS_TOKEN"
```

## Publishing Content

### Text Post
```bash
curl -X POST \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/feed" \
  -d "message=Your post content here" \
  -d "access_token=$FB_ACCESS_TOKEN"
```

### Photo Post
```bash
curl -X POST \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/photos" \
  -F "url=https://example.com/image.jpg" \
  -F "caption=Your photo caption" \
  -F "access_token=$FB_ACCESS_TOKEN"
```

### Link Post
```bash
curl -X POST \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/feed" \
  -d "link=https://example.com/article" \
  -d "message=Check out this article!" \
  -d "access_token=$FB_ACCESS_TOKEN"
```

## Content Management Workflows

### Schedule a Post
```python
# Python example for scheduled posting
import requests
from datetime import datetime, timedelta

# Schedule post for 1 hour from now
scheduled_time = int((datetime.now() + timedelta(hours=1)).timestamp())

data = {
    'message': 'This is a scheduled post',
    'published': 'false',
    'scheduled_publish_time': scheduled_time,
    'access_token': 'YOUR_ACCESS_TOKEN'
}

response = requests.post(f'https://graph.facebook.com/v18.0/{PAGE_ID}/feed', data=data)
```

### Batch Post Creation
```javascript
// Node.js batch operations
const FacebookAdsApi = require('facebook-nodejs-business-sdk').FacebookAdsApi;
const Page = require('facebook-nodejs-business-sdk').Page;

const api = FacebookAdsApi.init(accessToken);
const page = new Page(pageId);

const posts = [
    { message: 'Post 1 content' },
    { message: 'Post 2 content' },
    { message: 'Post 3 content' }
];

posts.forEach(async (post) => {
    await page.createFeed([], post);
});
```

## Analytics and Insights

```bash
# Get post performance metrics
curl -X GET \
  "https://graph.facebook.com/v18.0/$POST_ID/insights?metric=post_impressions,post_engaged_users,post_clicks&access_token=$FB_ACCESS_TOKEN"

# Get page insights for date range
curl -X GET \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/insights?metric=page_views,page_post_engagements&since=2024-01-01&until=2024-01-31&access_token=$FB_ACCESS_TOKEN"

# Get top performing posts
curl -X GET \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/posts?fields=message,created_time,shares,likes.summary(true),comments.summary(true)&limit=10&access_token=$FB_ACCESS_TOKEN"
```

## Decision Tree: Content Type Selection

```
Need to post content?
├── Text only → Use /feed endpoint with message parameter
├── Single image → Use /photos endpoint with url/source parameter
├── Multiple images → Use /feed endpoint with attached_media parameter
├── Video content → Use /videos endpoint
├── Link sharing → Use /feed endpoint with link parameter
└── Event promotion → Use /events endpoint
```

## Decision Tree: Publishing Strategy

```
When to publish?
├── Immediately → Set published=true
├── Later (scheduled) → Set published=false + scheduled_publish_time
└── Draft only → Set published=false (no schedule time)

What permissions needed?
├── Basic posting → pages_manage_posts
├── Reading insights → pages_read_engagement
├── Managing ads → pages_manage_ads
└── Live video → pages_manage_posts + pages_show_list
```

## Advanced Operations

### Manage Page Roles
```bash
# Get page admins/moderators
curl -X GET \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/roles?access_token=$FB_ACCESS_TOKEN"

# Add page role (requires admin access)
curl -X POST \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/roles" \
  -d "user=$USER_ID" \
  -d "role=MODERATOR" \
  -d "access_token=$FB_ACCESS_TOKEN"
```

### Webhook Configuration
```bash
# Subscribe to page webhooks
curl -X POST \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/subscribed_apps" \
  -d "subscribed_fields=feed,messages,messaging_postbacks" \
  -d "access_token=$FB_ACCESS_TOKEN"
```

## Common Rate Limits

```
Rate Limits:
- Standard: 200 calls per user per hour
- Marketing API: Varies by ad account
- Pages API: 4800 calls per hour per app
- Real-time updates: 50,000 calls per hour

Best Practices:
- Implement exponential backoff
- Cache access tokens (valid for 60 days)
- Batch requests when possible
- Monitor rate limit headers
```

## Troubleshooting

### Error: "Invalid OAuth access token"
```bash
# Check token validity
curl -X GET \
  "https://graph.facebook.com/v18.0/me?access_token=$FB_ACCESS_TOKEN"

# Get new long-lived token
curl -X GET \
  "https://graph.facebook.com/v18.0/oauth/access_token?grant_type=fb_exchange_token&client_id=$FB_APP_ID&client_secret=$FB_APP_SECRET&fb_exchange_token=$SHORT_LIVED_TOKEN"
```

### Error: "Insufficient privileges"
```
Solutions:
1. Request additional permissions: pages_manage_posts, pages_read_engagement
2. Use page access token, not user access token
3. Verify page role (must be admin/editor for posting)
4. Check app review status for restricted permissions
```

### Error: "Application request limit reached"
```bash
# Check current usage
curl -X GET \
  "https://graph.facebook.com/v18.0/$FB_APP_ID?fields=rate_limit_info&access_token=$FB_ACCESS_TOKEN"

# Implement rate limiting
sleep 3600  # Wait 1 hour before retrying
```

### Error: "Content policy violation"
```
Common causes:
- Spam-like content (repeated posts)
- Inappropriate images or text
- Misleading links
- Excessive capitalization or punctuation

Solutions:
- Review Facebook Community Standards
- Vary post content and timing
- Use authentic, original content
- Test posts manually first
```

### Debug Mode
```bash
# Use debug mode for detailed error info
curl -X GET \
  "https://graph.facebook.com/v18.0/debug_token?input_token=$FB_ACCESS_TOKEN&access_token=$APP_ACCESS_TOKEN"

# Check post delivery status
curl -X GET \
  "https://graph.facebook.com/v18.0/$POST_ID?fields=status_type,is_published&access_token=$FB_ACCESS_TOKEN"
```

## Performance Optimization

```bash
# Use field selection to reduce payload
curl -X GET \
  "https://graph.facebook.com/v18.0/$FB_PAGE_ID/posts?fields=id,message,created_time&access_token=$FB_ACCESS_TOKEN"

# Batch multiple requests
curl -X POST \
  "https://graph.facebook.com/v18.0/" \
  -d "batch=[{'method':'GET','relative_url':'me'},{'method':'GET','relative_url':'$PAGE_ID'}]" \
  -d "access_token=$FB_ACCESS_TOKEN"
```