Skip to main content
Turn on comment review when a community should read a comment before anyone else does. A held comment still belongs to its author, who can keep editing it, but it stays out of comment lists and public comment counts until a reviewer approves it. Reviewers work from a community-wide queue and approve or decline by comment ID.

Platform Support

Comment review is reached through a post’s community: a comment is held for review when it is written on a post that belongs to a community requiring review. Comments on stories, on your own content IDs, and on posts in a user’s feed are never held — see When Review Applies.Flutter does not ship comment review: it has no approval status, cannot read a review queue, and cannot approve a comment. It also does not filter comment queries, and the server returns an author’s own pending comments to them, so an author on Flutter sees their pending comment in comment lists as if it were published.Comment review is separate from post review. The two features have their own settings, their own permission, and their own status values — a comment is pending / approved / rejected, while a post is reviewing / published / declined.

Approval Lifecycle

Every comment carries an approvalStatus. This section is the single reference for when a comment is held, how its status moves, and what each move changes on the comment and its post. The method sections below show the calls.

When Review Applies

A comment is held for review only when all three of these are true:
  1. It is written on a post that belongs to a community. This includes replies: a reply on such a post is held under the same rule as a top-level comment.
  2. That community has needApprovalOnCommentCreation turned on. See Require Review for Community Comments.
  3. Its author cannot review that community’s comments. The community’s creator, and anyone who holds REVIEW_COMMUNITY_COMMENT on the community, publish immediately. Community moderators hold that permission by default.
Every other comment is approved when it is written. Changing the setting affects future transitions, not existing comments:
  • Turning review on changes no existing comment. A comment written before the switch enters review only if someone who cannot review later makes an effective edit to it. See How the Status Changes.
  • Turning review off does not drain the queue. Comments already pending stay pending, stay in the review queue, and can still be approved or declined.

Statuses

The server omits approvalStatus on a comment that has never been through review, which includes every comment written before this feature. Every SDK reads an absent value as approved. Read the value from the SDK model, not the field’s presence on the raw payload, and do not write your own defaulting.

Comment Queries Show Approved Comments Only

The TypeScript, iOS, and Android SDKs filter comment queries to approved comments, for every viewer, including the author of a pending comment. The same applies to a post’s latest-comment previews and to reply lists. You do not need to filter pending comments out yourself, and you cannot get one back through a comment query. To show an author their own pending comment, keep the comment that create or edit returns and render it outside the list, for example with an “Awaiting review” label. Reviewers read pending comments through the review queue.

How the Status Changes

An edit is effective when it changes the comment’s text, or when it sends attachments, links, or metadata at all, even the same values as before. An edit that sends only unchanged text leaves the status as it is.

What Approving or Declining Changes

Only approvalStatus records the outcome on the comment. The other changes land on visibility, counts, and events. The reviewer who decided, the time of the decision, and the decline reason are kept for the moderation record only. No SDK returns them.

Permission

Reading the queue and deciding on a comment both require the REVIEW_COMMUNITY_COMMENT permission on the target community. A client-side check is for hiding controls only; the server enforces the permission on every call, and a reviewer can never review their own comment.

Require Review for Community Comments

Set needApprovalOnCommentCreation when you create or update the community. After it is on, new comments and effective edits in that community enter the queue, unless their author can review the community’s comments. See Approval Lifecycle for the full rule.
Turning the setting off does not drain the queue. Comments already waiting stay waiting, and the review queue keeps serving them until each one is decided.

Read Approval Status on a Comment

Read the status on any comment you hold — including the one returned by create and edit — before you show it as published. In a community that requires review, a create or an effective edit comes back pending. Where review may apply, create comments with optimistic creation turned off. An optimistic create writes a local comment before the server answers, and that comment’s approvalStatus is only the SDK’s guess: it reads the community’s review setting from cache, and assumes pending when the post or its community is not cached. With optimistic creation off, nothing is written locally until the server confirms the comment, so the comment you receive carries the server’s status.
An author may keep editing their own pending comment unless the network turns that off. Read isAllowEditCommentWhenReviewingEnabled from social settings before you show an edit control: when it is false, editing a pending comment fails with 403 / 400300.

Query the Review Queue

List a community’s pending comments, newest first by when each entered the queue. A comment sent back for re-review returns to the top.
The review queue reports no total. There is no count on the response and no count endpoint, so an “N comments awaiting review” badge cannot be built on it. Page through the collection instead.

Approve or Decline a Comment

Approve to reveal the comment to everyone and move the post’s comment count by one. Decline to reject it — a declined comment is deleted at the same time. What Approving or Declining Changes lists every effect of both. Both calls take the comment ID. Decline also takes an optional reason, at most 250 characters, kept for the moderation record only.
reason is never shown to the comment’s author or to anyone else through the SDK. Do not build an author-facing rejection message on it.
Neither call is idempotent. A second decision on a comment that was already decided is refused, so two reviewers acting at once cannot both record an outcome.
Comment review changes how several other comment, post, and community APIs behave. The reference for each is on its own page; this table says only how review affects it.

Platform Notes

  • Counts. A pending comment does not count toward its post’s comment count or its parent’s reply count for anyone but its author. The count moves for everyone else on approval, so expect a count to change without a new comment appearing in the list. Two different counts express this: the server figure (post.commentsCount, what UIKit shows) stays approved-only for everyone, including the author, while the author’s own pending +1 is visible only through the SDK’s local count. Read it with getLocalCommentCount(includePending: true) on iOS and Android, or getLocalCommentCount(true) on TypeScript. Leave includePending at its default, false, for the count everyone else sees. The author’s +1 is session-scoped — it is gone after logout or app restart until the post is refetched.
Migrating from localCommentCount. post.localCommentCount is deprecated and now equals getLocalCommentCount(includePending: true). Move existing callers to getLocalCommentCount(includePending:) and choose the flag explicitly — true to include the author’s own pending comment (the old localCommentCount behavior), false for the shared, approved-only count.
  • Re-review. An effective edit can send an approved comment back to pending, and its count drops by one until it is approved again. How the Status Changes lists which edits do and which do not.
  • Session scope. Pending comments and the review queue are held for one signed-in user. They are dropped on logout and on user switch, and the queue stops loading if the user loses the review permission mid-session.
  • Return shapes follow each platform’s post-review API. TypeScript returns the comment, iOS returns nothing, and Android returns a Completable.

Post Review

Approve, decline, and query posts held for community review.

Edit Comment

Update comment text and attachments, and see when an edit needs review again.

Query Comments

List comments and replies on a post, story, or custom content ID.

Social Realtime Events

Subscribe to community and post topics so comment events reach the client.