Add Content-Bound Discussions to WordPress and Static Sites

Flow discussions add a backend-powered comment tree without using the WordPress comments database. They work on normal WordPress pages and on pages exported by Static Publisher because the browser reads and writes discussion data through the Flow backend.

A discussion has two coordinated blocks:

• the Flow Form collects root comments and replies and owns the authoritative backend policy;
• the Flow Discussion block lists public items and shows reply, edit, and delete actions when the current visitor has permission.

Their Form ID, content target, and discussion channel must match.

Add discussions to every post​

For a post type, add the Form and Discussion blocks to its Single template instead of copying them into individual post bodies. Set the target source to Current WordPress content. At runtime Flow identifies each post as:

wordpress / <post type> / <numeric post ID>

Every post therefore receives a separate thread while new posts inherit the same presentation and policy automatically.

Save the template or form source and confirm that Backend Sync succeeds before testing the frontend.

Configure the Flow Form​

Open Content binding and discussion on the Form block and enable Discussion. Flow then requires permanent submission retention, content binding, and a required content target.

Configure the backend policy on the Form:

• Allow replies: disable this for root comments without replies.
• Maximum reply depth: 1 through 5. Root comments have depth 0, so 1 permits one direct reply level.
• Moderation: publish automatically or hold new items for moderation.
• Comment access: anonymous, optional sign-in, or required sign-in.
• Allowed Cognito groups: optionally restrict mutations to members of any listed group.
• Public author name source: a form field or verified Cognito attributes.
• Public body field: the text field exposed as the comment body.
• Discussion rating field: optionally choose a Rating field for root-comment ratings and discussion-level aggregation. Replies do not contain ratings.
• Optional author edit window, author deletion, and moderator deletion.

The Form definition is the backend source of truth. Keep the Discussion block's access and group settings aligned so its frontend actions accurately represent that policy.

Configure the Discussion block​

Form ID​

The Form ID selects the synchronized backend form. When left empty, the WordPress renderer attempts to use the synchronized form ID stored for the current content. Use an explicit value when a reusable pattern or template cannot inherit the correct form metadata.

Target source​

The Form must submit the same target that the Discussion block reads. A target mismatch usually looks like a valid but empty discussion.

Discussion channel​

The channel connects browser events between the Form and Discussion instances on the page. It determines which form opens for a reply and which list refreshes after submission. Empty channels are derived from the Form ID and target.

A channel is not a backend partition key. Changing only the channel does not create a second thread for the same Form ID and content target.

Access and Cognito groups​

• Anonymous visitors: no identity is required for mutations.
• Visitors or signed-in users: anonymous visitors are accepted when no group restriction is configured; signed-in visitors receive owner capabilities.
• Signed-in users only: comment, reply, edit, and delete mutations require a verified Cognito access token as applicable.

Group names are exact and case-sensitive, and matching any listed group is enough. With optional authentication and a non-empty group list, only signed-in members of those groups can comment.

Discussion reading is a separate policy. The normal public GET does not validate a token merely because one happens to be available. Authentication is used only for optional capability enrichment or protected mutations.

Pagination and previews​

• Root page size controls root comments fetched per page: 1–50, default 20.
• Reply page size controls direct replies fetched for a selected parent: 1–50, default 10.
• Reply preview count includes 0–5 direct replies with each initially loaded root; 0 disables only previews.

The header count is based on loaded roots and their backend-provided descendant totals. If another root page exists, Flow appends +, so it is not yet an exact discussion-wide total.

Ratings and filters​

Select a Discussion rating field on the Form to publish ratings with root comments. Flow uses the selected Rating block's star count and fraction setting, so whole, half, and third-star steps are supported without rounding. While the Form is replying, it hides that field; the backend also prevents replies from supplying ratings.

The Discussion block can display a global summary with:

• the number of currently visible, rated root comments;
• their derived average;
• every allowed rating bucket's count and percentage.

It can also let visitors show all root comments, an exact rating, ratings at least a chosen value, or ratings at most a chosen value. The filter applies only to roots, while replies remain attached to their parent. The summary always describes the complete discussion, not only the filtered page. Authors can hide the summary or filter and can configure the initial filter in the inspector.

The backend stores bucket counts rather than a rounded average. Publication, moderation, hide/spam, republication, owner rating edits, deletion, and privacy purge update those counts in the same transaction as the comment state change. The average and percentages are calculated when the discussion is read.

Labels and dates​

The inspector can override the title; loading, empty, error, and retry copy; author and tombstone labels; reply and pagination labels; count labels; and edit/delete confirmation copy. Count labels support a {count} placeholder. Otherwise Flow uses its localized AWS Amplify I18n strings and the language in the Flow store.

Dates can be hidden or formatted with full, long, medium, or short styles. The browser formats them with the selected locale and its local time zone.

Static-site requirements​

An exported discussion page still needs:

• the Flow frontend assets and encoded block configuration;
• a reachable Flow backend URL;
• the exported origin allowed by the backend/CORS configuration;
• a stable Form ID and content reference.

No WordPress comment endpoint is required. Public reading and authenticated mutation remain separate, which allows a static page to show all public comments while requiring Cognito sign-in to add or manage them.

Current limits​

• Reply depth is capped at five.
• Set Allow replies off for no replies; maximum depth 1 still allows one reply layer.
• The 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. Existing buckets require explicit reconciliation before that configuration changes.
• Public responses carry the Form's non-sensitive reply policy. The frontend therefore observes the same allowReplies and maximum-depth boundary for anonymous and signed-in visitors.

Troubleshooting​

1. Verify the Form's backend sync status and resolved Form ID.
2. Compare the Form and Discussion target source and resolved content reference.
3. Align their channel, comment access, and Cognito groups.
4. Treat public read errors separately from comment-permission errors.
5. Check moderation status for comments that submitted successfully but do not appear.
6. For exported pages, verify Flow assets, backend URL, allowed origin, and canonical URL stability.