## Flow Discussions & Comments

Flow can provide content-bound public comments and reply trees without storing comments in WordPress. The frontend talks directly to the Flow backend, so the same discussion continues to work after Static Publisher exports the page.

### Form and Discussion responsibilities

A working discussion uses two coordinated blocks:

- the **Flow Form** creates root comments and replies and contains the authoritative backend policy;
- the **Flow Discussion** block lists published items and presents reply, edit, and delete actions when allowed.

Keep their Form ID, content target, discussion channel, access mode, and Cognito group settings aligned.

For posts, put both blocks in the Single template rather than in each post body. Select **Current WordPress content** so every post automatically receives a separate `wordpress / post type / post ID` thread.

### Form-side policy

Enable **Discussion** in the Form's content binding and discussion settings. Discussion mode requires permanent retention, enabled content binding, and a required target.

- Turn **Allow replies** off when users may add root comments but no replies.
- **Maximum reply depth** accepts 1–5. Root comments are depth 0, so 1 still allows one direct reply level.
- Choose automatic publication or required moderation.
- Choose anonymous, optional, or required Cognito identity.
- Optionally restrict mutations to any of the listed Cognito groups.
- Select the public author-name source and the public body field.
- Optionally select a Rating field to publish and aggregate ratings on root
  comments. Replies never contain a rating.
- Optionally enable owner editing, an edit window, owner deletion, and moderator deletion.

The backend enforces these Form settings even if a frontend action is shown incorrectly.

### Discussion block identity

**Form ID** selects the synchronized backend form. If empty, WordPress attempts to use the synchronized ID stored for the current content.

**Target source** identifies the discussed item:

- **Current WordPress content**: current post type and numeric post ID;
- **Explicit content reference**: authored namespace, type, and ID;
- **Canonical page URL**: stable canonical origin and path.

**Discussion channel** connects browser events between the matching Form and Discussion instances. It is not a backend partition key, so changing only the channel does not create another thread.

### Reading and commenting permissions

Public reading is independent from commenting permission. The normal discussion GET does not validate a token merely because the browser has one.

- **Anonymous visitors** can mutate without identity when the Form policy permits it.
- **Visitors or signed-in users** allows anonymous visitors only when no group restriction applies; authenticated visitors can receive owner capabilities.
- **Signed-in users only** requires a verified Cognito access token for protected mutations.

Group matching is exact and case-sensitive. Membership in any listed group is enough. Optional authentication plus a non-empty group list effectively requires a signed-in group member.

### Pagination, counts, and dates

- **Root page size**: root comments per request, 1–50.
- **Reply page size**: direct replies per parent request, 1–50.
- **Reply preview count**: direct replies initially included with each root, 0–5. Zero disables only the preview.

The initial comment total is calculated from loaded roots and their descendant counts. A `+` means more root pages exist, so the displayed value is not yet an exact global total.

The block can localize or override its visible labels and can hide dates or format them with full, long, medium, or short locale-aware styles.

### Ratings and filtering

When the Form selects a discussion Rating field, Flow uses its star count and
fraction setting. Whole, half, and third-star steps are supported. The field is
hidden for replies, and the backend accepts ratings only on root comments.

The Discussion block can show a global rated-comment count, average, and bucket
breakdown with counts and percentages. Visitors can filter roots by an exact
rating, at least a rating, or at most a rating. Replies remain attached to their
root and are not filtered independently. The block author can hide the summary
or filter and choose an initial filter.

Only visible, published root comments contribute to the buckets. Flow updates
the bucket counts transactionally when a comment is published, moderated,
hidden, marked as spam, republished, edited, deleted, or privacy-purged. Average
and percentages are derived on read rather than stored.

### Static-site checklist

An exported discussion needs:

1. Flow frontend assets and the block configuration;
2. a reachable Flow backend;
3. the exported origin allowed by backend/CORS settings;
4. stable Form ID and content reference values.

WordPress comment APIs are not required. Public reads may stay anonymous while Cognito protects comment, reply, edit, and delete operations.

### Current limitations

- Five reply levels is the hard maximum.
- Use **Allow replies = off** for no replies; depth 1 is not the no-reply setting.
- The display inspector does not currently expose sort direction or initial reply-depth controls.
- Treat the selected rating field's star count and fraction setting as immutable
  after ratings have been published. Changing it requires reconciliation of the
  existing buckets.
- Public responses include the Form's non-sensitive reply policy, so the
  frontend uses the configured reply toggle and maximum depth for every visitor.

For the complete setup and troubleshooting guide, see [Flow Discussions & Comments](https://wpsuite.io/docs/flow/discussion/).