facebook

Files (1)

• SKILL.md

SKILL.md (first lines)

Call the **Facebook Graph API** (`graph.facebook.com`) with `curl + jq`. The
connector injects `$FACEBOOK_ACCESS_TOKEN` (a **Page** access token with
`pages_manage_posts` + `pages_read_engagement`) and optionally
`$FACEBOOK_PAGE_ID`. Never echo them.

The Graph API publishes only to a **Facebook Page** you manage — it cannot post
to a personal profile timeline.

### Resolve the Page id

If `$FACEBOOK_PAGE_ID` is set, use it. Otherwise derive it from the token — try
the **Page-token** path first (`/me` is the Page), then fall back to the
**user-token** path (`/me/accounts` → first managed Page), so either token type
the connector accepts resolves cleanly:

```bash
if [ -n "$FACEBOOK_PAGE_ID" ]; then
  PAGE="$FACEBOOK_PAGE_ID"
else
  # Page access token: /me IS the Page
  PAGE=$(curl -sS "https://graph.facebook.com/v21.0/me?fields=id,name&access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r 'select(.name).id // empty')
  if [ -z "$PAGE" ]; then
    # User access token: list the managed Pages, take the first
    PAGE=$(curl -sS "https://graph.facebook.com/v21.0/me/accounts?access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r '.data[0].id // empty')
  fi
fi
echo "page_id=$PAGE"
```

Errors are JSON with `error.message` / `error.code` — show them verbatim.
`401` / `OAuthException` → token expired or missing scope; a null `PAGE` → the
token isn't a Page token / manages no Page (see Gotchas). Reconnect if needed.

> If the user token path is used, `/me/accounts` also returns a per-Page
> `access_token` in `.data[0].access_token`. Prefer that Page token for the
> publish call when the injected token is a user token; a Page's own token is
> what `pages_manage_posts` actually authorizes.

## Publish a text or link post

**Confirm the message (and link, if any) with the user first.** Post to
`/{page-id}/feed`:

```bash
# Text-only post
curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/feed" \
  --data-urlencode "message=One endpoint → posters, cards, mockups. #AI #API" \
  -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
# → {"id":"<PAGE_ID>_<POST_ID>"}

# Link post — Facebook renders a link preview card from the URL
curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/feed" \
  --data-urlencode "message=Read our new guide 👇" \
  -d "link=https://acedata.cloud/blog/xxxx" \
  -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
```

## Publish a photo post

Post to `/{page-id}/photos` with a **public image URL** (Facebook server-side
fetches it); `caption` is the post text:

```bash
curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/photos" \
  -d "url=https://cdn.acedata.cloud/xxxx.jpg" \
  --data-urlencode "caption=One endpoint → posters, cards, mockups. #AI #API" \
  -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
# → {"id":"<PHOTO_ID>","post_id":"<PAGE_ID>_<POST_ID>"}
```

To attach **multiple photos** to one post: upload each with `published=false` to
get its media id, then create the feed post with
`attached_media[0]={"media_fbid":"<ID1>"}` … for each.

## Get the post permalink

Use the returned `post_id` (or `id`) to fetch the live URL to hand back:

```bash
curl -sS "https://graph.facebook.com/v21.0/<PAGE_ID>_<POST_ID>?fields=permalink_url&access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r .permalink_url
```

## Read recent Page posts

```bash
curl -sS "https://graph.facebook.com/v21.0/$PAGE/posts?fields=id,message,created_time,permalink_url&limit=10&access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
```

## Gotchas

- **Pages only, not profiles** — the Graph API cannot publish to a personal
  timeline. If the user asks to post to their profile, explain this limitation.
- **Page token, not user token** — publishing needs a Page access token with
  `pages_manage_posts`. If you only have a user token, resolve the Page token via
  `/me/accounts` (see above). A `(#200)` permissions error means the token lacks
  `pages_manage_posts` or the user isn't an admin of the Page.
- **Photo URL must be public** on a server Facebook can reach; local files won't
  work. Host on cdn.acedata.cloud first.
- **Page Publishing Authorization (PPA):** some Pages must complete PPA before API
  publishing works — surface the API error verbatim if it mentions PPA.
- **Token expiry:** a Page token derived from a short-lived user token expires
  fast. If posting 401s soon after connecting, the user needs a long-lived Page
  token — surface the `OAuthException` verbatim and suggest reconnecting.
- API version: keep the `vXX.0` path current if you hit a version/deprecation error.

## Record the output

After you successfully publish and obtain the live permalink, call the built-in
`publish_artifact` tool ONCE so the user can track it in **My Outputs**:

```
publish_artifact(kind="post", channel="facebook", title="<title>", url="<the REAL permalink>", status="delivered")
```

Use the real returned URL — never fabricate one. Call it once per published item,
only after delivery is confirmed; skip it (or use `status="failed"`) if publishing failed.
See `_shared/artifacts.md`.

From AceDataCloud/Skills, Apache-2.0.

More from AceDataCloud/Skills