Skip to main content

Documentation Index

Fetch the complete documentation index at: https://info.bundle.social/llms.txt

Use this file to discover all available pages before exploring further.

Facebook Page Reviews are handled through an async import flow. You queue an import, poll status, then work with normalized review records in our API.
Facebook calls Page reviews recommendations in parts of its API. That is why these endpoints use /recommendations, even though this guide calls the feature Facebook Page Reviews.

​
How it works

This is an asynchronous job, same idea as Google Business Reviews:
  1. Start: Trigger an import (“Fetch 50 reviews for this Page”).
  2. Wait: We fetch from Facebook and process the batch.
  3. Poll: Check import status.
  4. Fetch: Read imported reviews from the recommendations endpoint.
  5. Reply: Reply to the review or to comments inside the recommendation thread.

​
Step 1: Start the Import

Endpoint: POST /api/v1/misc/facebook/recommendations/import 
{
  "teamId": "team_123",
  "count": 50
}

​
Rules & Limits

  • count range: 1-100 per request.
  • One active import per social account: if one is already running or recently completed, you’ll get 409.
  • Monthly limit per social account (default):
    • Free: 5 reviews / month
    • Pro: 100 reviews / month
    • Business: 250 reviews / month
These are defaults. Organizations can have custom review-import limits configured.

​
Step 2: Check Import Status

Endpoints:
  • GET /api/v1/misc/facebook/recommendations/import?teamId=team_123
  • GET /api/v1/misc/facebook/recommendations/import/:importId
The list endpoint returns up to 20 latest imports for that team/Page, newest first.

​
Statuses

  • PENDING: Waiting in queue.
  • FETCHING_RECOMMENDATIONS: Import is running.
  • COMPLETED: Finished.
  • FAILED: Import failed after retries.
  • RATE_LIMITED: Temporarily paused due to API/rate pressure; resumes automatically after rateLimitResetAt.
Example import object: 
{
  "id": "imp_fb_abc123",
  "teamId": "team_123",
  "socialAccountId": "sa_123",
  "requestedCount": 50,
  "status": "FETCHING_RECOMMENDATIONS",
  "itemsImported": 24,
  "error": null,
  "rateLimitResetAt": null,
  "startedAt": "2026-04-27T10:00:00.000Z",
  "completedAt": null,
  "createdAt": "2026-04-27T09:59:55.000Z",
  "updatedAt": "2026-04-27T10:00:08.000Z",
  "deletedAt": null
}

​
Step 3: Fetch Imported Reviews

Endpoints:
  • GET /api/v1/misc/facebook/recommendations?teamId=team_123&limit=50&offset=0
  • GET /api/v1/misc/facebook/recommendations/:recommendationId?teamId=team_123

​
Query Parameters (GET /recommendations)

ParameterTypeDefaultDescription
teamIdstringrequiredTeam ID
limitnumber50Page size (1-100)
offsetnumber0Pagination offset
Example response: 
{
  "recommendations": [
    {
      "id": "rec_123",
      "socialAccountId": "sa_123",
      "teamId": "team_123",
      "externalRecommendationId": "1234567890",
      "openGraphStoryId": "9876543210",
      "reviewerDisplayName": "Jane Doe",
      "reviewerProfilePhotoUrl": "https://platform-lookaside.fbsbx.com/...",
      "recommendationValue": "RECOMMEND",
      "rating": null,
      "comment": "Great service and very fast support.",
      "hasMedia": false,
      "mediaSummary": [],
      "ownerReplyComment": "Thanks a lot for your feedback!",
      "ownerReplyCommentId": "comment_123",
      "ownerReplyUpdatedAt": "2026-04-27T12:15:00.000Z",
      "createTime": "2026-04-26T18:22:00.000Z",
      "updateTime": "2026-04-27T12:15:00.000Z",
      "importedAt": "2026-04-27T12:15:02.000Z",
      "createdAt": "2026-04-27T12:15:02.000Z",
      "updatedAt": "2026-04-27T12:15:02.000Z",
      "deletedAt": null
    }
  ],
  "total": 1,
  "limit": 100,
  "remainingCapacity": 99
}
recommendationValue values: RECOMMEND, NOT_RECOMMEND, UNKNOWN. limit in this response is your monthly import cap for that social account (not the page size).

​
Step 4: Reply to Reviews

​
Reply to a Review

Endpoint: PUT /api/v1/misc/facebook/recommendations/:recommendationId/reply 
{
  "teamId": "team_123",
  "comment": "Thank you for visiting us!"
}
comment length: 1-4096 chars. This creates a Facebook comment on the Page review story and stores it as ownerReplyComment.

​
Fetch Thread Comments

Endpoint: GET /api/v1/misc/facebook/recommendations/:recommendationId/comments?teamId=team_123 
{
  "comments": [
    {
      "id": "comment_123",
      "recommendationId": "rec_123",
      "rootObjectId": "9876543210",
      "parentCommentId": null,
      "authorName": "Jane Doe",
      "authorExternalId": "fb_user_123",
      "authorAvatarUrl": "https://platform-lookaside.fbsbx.com/...",
      "text": "One more detail from the customer.",
      "likesCount": 2,
      "repliesCount": 1,
      "canReply": true,
      "createdTime": "2026-04-27T13:00:00.000Z"
    }
  ],
  "total": 1
}

​
Reply to a Thread Comment

Endpoint: PUT /api/v1/misc/facebook/recommendations/:recommendationId/comments/:commentId/reply 
{
  "teamId": "team_123",
  "comment": "Happy to help!"
}
Response: 
{
  "id": "reply_comment_123"
}

​
Quirks & Gotchas

​
Reviews Are Recommendations

Facebook’s native model is recommendation-based, not star-review-based. Some records may have rating: null; use recommendationValue as the primary signal.

​
Some Reviews Cannot Be Replied To

Replies require openGraphStoryId. If Facebook does not expose it for a review, reply and thread endpoints return an error instead of pretending the action worked.

​
Incremental Sync

Re-running imports is safe. Reviews are upserted by external recommendation ID, so existing records are updated instead of duplicated.

​
Temporary RATE_LIMITED Is Normal

When Facebook slows things down, imports switch to RATE_LIMITED and auto-resume. No manual retry endpoint needed for this path.

​
Capacity Is Per Social Account

remainingCapacity is calculated per connected Facebook social account, not globally across all accounts.