# facebook-graph

Meta Graph API. Covers Facebook reviews/recommendations and Instagram/Facebook posting (Phase 2 social-poster).

## What we use (reviews + responses)

- **Page ratings:** `GET /v18.0/{page-id}/ratings?fields=open_graph_story,recommendation_type,review_text,reviewer,created_time` - returns recent Facebook recommendations / reviews
- **Reply to a rating:** Facebook deprecated programmatic responses to ratings in 2018. Operators reply via the Facebook page UI. The response-drafter generates a draft; the app surfaces it with a "Copy to Facebook" button.

## What we use (Phase 2 social posting)

- **Post to page:** `POST /v18.0/{page-id}/feed`
- **Post to Instagram (via FB Graph):** `POST /v18.0/{ig-user-id}/media` then `POST /v18.0/{ig-user-id}/media_publish`

## Scopes

- `pages_read_engagement` - read page ratings.
- `pages_manage_posts` - publish posts (Phase 2 only).
- `pages_messaging` - NOT requested. We do not message customers via Messenger.
- `business_management` - for multi-location brands using Meta Business Manager.

## Auth

OAuth via Facebook Login for Business. Long-lived page access tokens stored encrypted in D1.

## Rate limits

- Per-app: 200 calls per hour per user.
- Per-page: 4,800 calls per 24 hours per page.
- We poll ratings per location every 10 minutes (~144 calls/day per location), well within limits.

## Failure modes

- **190 OAuthException:** token revoked or expired. Operator re-grants in settings.
- **17 (User request limit reached):** rate limit. Back off.
- **100 (Permission denied):** scope was removed by the operator. Show a "reconnect required" prompt.

## Compliance

- Meta prohibits "engagement bait" (tag a friend to win, share to enter). Enforced by respect-platform-tos.
- Meta prohibits programmatic responses to reviews on Facebook Pages. Enforced; we deep-link to the UI.
- Meta prohibits automated direct messaging without an opt-in flow. Enforced; social-poster never DMs.

## Not done in CL-002

The Graph adapter is not yet implemented. Ships in a later CL alongside the OAuth onboarding flow.