Facebook Page

v1.0.1

Facebook Page API integration with managed OAuth. Manage pages, posts, comments, insights, photos, videos, and product catalogs. Use this skill when users wa...

0· 22· 2 versions· 0 current· 0 all-time· Updated 3h ago· MIT-0

by@byungkyu

Security Scans

VirusTotalBenign ClawScanBenign Static analysisBenign

Install

openclaw skills install facebook-page-api

Facebook Page

Access the Facebook Graph API with managed OAuth authentication. Manage pages, publish and read posts, view page insights, manage comments, and access photos and videos.

Quick Start

# List your Facebook Pages
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/facebook-page/v25.0/me/accounts?fields=id,name,category,fan_count,followers_count')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://api.maton.ai/facebook-page/{native-api-path}

Maton proxies requests to graph.facebook.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

Sign in or create an account at maton.ai
Go to maton.ai/settings
Copy your API key

Connection Management

Manage your Facebook Page OAuth connections at https://api.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=facebook-page&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'facebook-page'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "facebook-page",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Facebook Page connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/facebook-page/v25.0/me/accounts?fields=id,name')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always include this header to ensure requests go to the intended account.

Security & Permissions

Access is scoped to pages, posts, comments, insights, photos, videos, and product catalogs within the connected Facebook Page account.
All write operations require explicit user approval. Before publishing posts, uploading photos, posting comments, or deleting content, confirm the target page, resource, and intended effect with the user.
Publishing posts and comments are publicly visible. Always confirm post content and target page with the user before publishing, as these actions are immediately visible to the page's audience.

API Reference

Page Access Token

Most page-specific endpoints (feed, insights, comments, etc.) require a Page Access Token. The gateway injects a User Access Token, but the Facebook API requires a Page Access Token for page operations. Endpoints that only need a User Access Token (like GET /me/accounts and GET /{page_id}) work without a Page Access Token.

Retrieve the page access token from /me/accounts and pass it as a query parameter access_token in subsequent requests:

python <<'EOF'
import urllib.request, os, json
# Step 1: Get page token
req = urllib.request.Request('https://api.maton.ai/facebook-page/v25.0/me/accounts?fields=id,name,access_token')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
pages = json.load(urllib.request.urlopen(req))
page_id = pages['data'][0]['id']
page_token = pages['data'][0]['access_token']

# Step 2: Use page token for page-specific endpoints
req = urllib.request.Request(f'https://api.maton.ai/facebook-page/v25.0/{page_id}/feed?fields=id,message,created_time&limit=10&access_token={page_token}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Page Management

List Pages

Returns all Facebook Pages managed by the authenticated user. Works with the gateway-injected User Access Token (no access_token query parameter needed).

GET /facebook-page/v25.0/me/accounts?fields=id,name,category,fan_count,followers_count

Response:

{
  "data": [
    {
      "id": "953430301193656",
      "name": "Maton",
      "category": "Software",
      "fan_count": 0,
      "followers_count": 0
    }
  ],
  "paging": {
    "cursors": {
      "before": "...",
      "after": "..."
    }
  }
}

Available Fields: id, name, access_token, category, category_list, tasks

Get Page Details

Returns details for a specific page. Works with User Access Token.

GET /facebook-page/v25.0/{page_id}?fields=id,name,about,category,fan_count,followers_count,website,phone,emails,link,verification_status

Response:

{
  "id": "953430301193656",
  "name": "Maton",
  "category": "Software",
  "fan_count": 0,
  "followers_count": 0,
  "link": "https://www.facebook.com/953430301193656",
  "verification_status": "not_verified"
}

Available Fields: id, name, about, description, category, category_list, fan_count, followers_count, talking_about_count, cover, picture, website, phone, emails, location, hours, link, verification_status, is_published

Posts

All post endpoints require a Page Access Token passed as the access_token query parameter.

Get Page Feed

GET /facebook-page/v25.0/{page_id}/feed?fields=id,message,created_time,type&limit=10&access_token={page_access_token}

Response:

{
  "data": [
    {
      "id": "953430301193656_122095067559277233",
      "message": "Hello world!",
      "created_time": "2026-02-16T06:47:45+0000"
    }
  ],
  "paging": {
    "cursors": {
      "before": "...",
      "after": "..."
    }
  }
}

Get Published Posts

GET /facebook-page/v25.0/{page_id}/published_posts?fields=id,message,created_time&limit=10&access_token={page_access_token}

Publish a Post

POST /facebook-page/v25.0/{page_id}/feed?access_token={page_access_token}
Content-Type: application/json

{
  "message": "Hello from my page!"
}

Response:

{
  "id": "953430301193656_122110982931277233"
}

Available Fields:

message (string) - Post text content
link (string) - URL to attach
published (boolean) - Set false to create an unpublished/draft post
scheduled_publish_time (int) - UNIX timestamp for scheduling future posts
place (string) - Location ID to tag
tags (string) - Comma-separated user IDs to tag (requires place)

Publish a Link Post

POST /facebook-page/v25.0/{page_id}/feed?access_token={page_access_token}
Content-Type: application/json

{
  "message": "Check out this article!",
  "link": "https://example.com/article"
}

Update a Post

POST /facebook-page/v25.0/{post_id}?access_token={page_access_token}
Content-Type: application/json

{
  "message": "Updated post content"
}

Response:

{
  "success": true
}

Delete a Post

DELETE /facebook-page/v25.0/{post_id}?access_token={page_access_token}

Response:

{
  "success": true
}

Comments & Engagement

All comment endpoints require a Page Access Token.

Get Comments on a Post

GET /facebook-page/v25.0/{post_id}/comments?fields=id,message,from,created_time&access_token={page_access_token}

Response:

{
  "data": [
    {
      "id": "122110982931277233_2054970148765241",
      "message": "Great post!",
      "from": {
        "name": "User Name",
        "id": "123456789"
      },
      "created_time": "2026-04-13T22:00:00+0000"
    }
  ]
}

Delete a Comment

DELETE /facebook-page/v25.0/{comment_id}?access_token={page_access_token}

Page Insights

Page Insights endpoints require a Page Access Token.

Get Page Insights

GET /facebook-page/v25.0/{page_id}/insights?metric=page_views_total,page_posts_impressions,page_video_views&period=day&access_token={page_access_token}

Available Metrics:

Metric	Description
`page_views_total`	Total page views
`page_posts_impressions`	Total impressions of page posts
`page_video_views`	Total video views on the page

Deprecated Metrics:

Deprecated	Use Instead
`page_impressions`	`page_views_total`
`page_engaged_users`	`page_posts_impressions`
`page_fans`	`fan_count` field on page

Period Values: day, week, days_28

Get Page Insights with Date Range

GET /facebook-page/v25.0/{page_id}/insights?metric=page_views_total&period=day&since=2026-01-01&until=2026-01-31&access_token={page_access_token}

Response:

{
  "data": [
    {
      "name": "page_views_total",
      "period": "day",
      "values": [
        {
          "value": 150,
          "end_time": "2026-01-02T08:00:00+0000"
        }
      ],
      "title": "Total views",
      "id": "{page_id}/insights/page_views_total/day"
    }
  ],
  "paging": {
    "previous": "...",
    "next": "..."
  }
}

Photos

Get Page Photos

GET /facebook-page/v25.0/{page_id}/photos?fields=id,name,created_time,images&limit=10&access_token={page_access_token}

Response:

{
  "data": [
    {
      "id": "122095067559277233",
      "created_time": "2026-02-16T06:48:02+0000",
      "images": [
        {
          "height": 512,
          "source": "https://scontent.xx.fbcdn.net/...",
          "width": 512
        }
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "...",
      "after": "..."
    }
  }
}

Upload a Photo

POST /facebook-page/v25.0/{page_id}/photos?access_token={page_access_token}
Content-Type: application/json

{
  "url": "https://example.com/photo.jpg",
  "caption": "My photo caption"
}

Videos

Get Page Videos

GET /facebook-page/v25.0/{page_id}/videos?fields=id,title,description,created_time&limit=10&access_token={page_access_token}

Product Catalogs

Get Product Catalogs

GET /facebook-page/v25.0/{page_id}/product_catalogs?access_token={page_access_token}

Response:

{
  "data": [
    {
      "id": "catalog_id",
      "name": "My Product Catalog"
    }
  ]
}

Get Products in a Catalog

GET /facebook-page/v25.0/{catalog_id}/products?fields=id,name,price,image_url&access_token={page_access_token}

Response:

{
  "data": [
    {
      "id": "product_id",
      "name": "Example Product",
      "price": "$19.99",
      "image_url": "https://example.com/product.jpg"
    }
  ]
}

Pagination

The Facebook Graph API uses cursor-based pagination. Responses include paging.cursors.before and paging.cursors.after values.

GET /facebook-page/v25.0/{page_id}/feed?fields=id,message&limit=10&after={after_cursor}&access_token={page_access_token}

Response includes pagination info:

{
  "data": [...],
  "paging": {
    "cursors": {
      "before": "...",
      "after": "..."
    },
    "next": "https://graph.facebook.com/...",
    "previous": "https://graph.facebook.com/..."
  }
}

Use the after cursor value for the next page, and before for the previous page. The limit parameter controls the number of results per page (max 100 for feed).

Code Examples

JavaScript

// Step 1: Get page token
const accountsRes = await fetch(
  'https://api.maton.ai/facebook-page/v25.0/me/accounts?fields=id,name,access_token',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const accounts = await accountsRes.json();
const pageId = accounts.data[0].id;
const pageToken = accounts.data[0].access_token;

// Step 2: Get page feed
const feedRes = await fetch(
  `https://api.maton.ai/facebook-page/v25.0/${pageId}/feed?fields=id,message,created_time&limit=10&access_token=${pageToken}`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const feed = await feedRes.json();

Python

import os
import requests

headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}

# Step 1: Get page token
accounts = requests.get(
    'https://api.maton.ai/facebook-page/v25.0/me/accounts',
    headers=headers,
    params={'fields': 'id,name,access_token'}
).json()
page_id = accounts['data'][0]['id']
page_token = accounts['data'][0]['access_token']

# Step 2: Get page feed
feed = requests.get(
    f'https://api.maton.ai/facebook-page/v25.0/{page_id}/feed',
    headers=headers,
    params={
        'fields': 'id,message,created_time',
        'limit': 10,
        'access_token': page_token
    }
).json()

Notes

Most page-specific endpoints (feed, insights, comments, photos, videos) require a Page Access Token passed as the access_token query parameter
The GET /me/accounts and GET /{page_id} endpoints work with the gateway-injected User Access Token directly
Post IDs follow the format {page_id}_{post_id}
Approximately 600 ranked, published posts per year are accessible via the feed endpoint
Some older insight metrics are deprecated — use the updated metric names listed in the Insights section
IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Status	Meaning
400	Missing Facebook Page connection
401	Invalid or missing Maton API key
190	Invalid OAuth Access Token (Facebook error code)
200	Permissions error - missing required scope (Facebook error code)
429	Rate limited
4xx/5xx	Passthrough error from Facebook Graph API

Troubleshooting: API Key Issues

Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Page Access Token Required

If you get a "This method must be called with a Page Access Token" error, you need to include the page's access token as a query parameter. See the Page Access Token section above.

Troubleshooting: Invalid App Name

Ensure your URL path starts with facebook-page. For example:

Correct: https://api.maton.ai/facebook-page/v25.0/me/accounts
Incorrect: https://api.maton.ai/v25.0/me/accounts

Resources

Version tags

latestvk97exnkg51y0kw8pt26mnzcrx185x8gn

Runtime requirements

🧠 Clawdis

EnvMATON_API_KEY

Facebook Page

Security Scans

Install

Facebook Page

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

Security & Permissions

API Reference

Page Access Token

Page Management

List Pages

Get Page Details

Posts

Get Page Feed

Get Published Posts

Publish a Post

Publish a Link Post

Update a Post

Delete a Post

Comments & Engagement

Get Comments on a Post

Post a Comment

Delete a Comment

Page Insights

Get Page Insights

Get Page Insights with Date Range

Photos

Get Page Photos

Upload a Photo

Videos

Get Page Videos

Product Catalogs

Get Product Catalogs

Get Products in a Catalog

Pagination

Code Examples

JavaScript

Python

Notes

Error Handling

Troubleshooting: API Key Issues

Troubleshooting: Page Access Token Required

Troubleshooting: Invalid App Name

Resources

Version tags

Runtime requirements