Comments and product reviews are the same record: a comment (comment) whose owner is the thing it is on. A comment on a product (sf_product) is a review and can carry a star rating. Anything else, such as a post or a page, gets a plain comment (appengine comments/comment-rules.ts 142). Visitors write them under a blog post (Write and publish a blog post) and on a product page (Catalog pages from products). Staff read and decide them in Comments (/comment).
"Tested" below means checked on the local engine with test posts, a test product and @test.local customers, all deleted afterwards. The rule order is also covered by the engine's own specs (comments.moderation.spec.ts, comments.verified-purchase.spec.ts, 51 passing). Everything else is read from the code, with the file named.
The rules, and where they live
Per site: site.data.comments. Set in Site Config → Comments, or Comments → Comment settings (websitemint comment/site-comment-settings.tsx). Defaults are in commentSettings (comment-rules.ts 81–98):
| Studio label | Field | Values (default first) | What it does |
|---|---|---|---|
| Comments on posts and pages | enabled | true / false | Off: "Comments are turned off on this site." |
| Product reviews | reviewsEnabled | true / false | Off: "Reviews are turned off for this store." |
| Who may comment | whoMayComment | signed_in / anyone | anyone lets a guest post with a name and an email |
| When a comment shows | showWhen | immediately / after_first_approval / after_approval | See the order below |
| AI assistant | aiAssistant | an ai_assistant name, or empty | Decides waiting comments; empty means a person does |
| Hold a comment with more links than | maxLinks | 2 | More links than this: held for review |
| Send for review after this many reports | reportThreshold | 3 (at least 1) | From different people |
| Close comments after | closeAfterDays | 0 (never) | Days after the post was published |
| Notify | notify | email list, empty | Who is told (see Notifications) |
Whole business: blocked words and people, read and written by GET / PUT comments/settings with { blockedWords, blockedWordsAction: "review" | "reject", blockedPeople }. Studio: Comments → Blocked words and people. It is saved as the comments setting (comments.service.ts 282–298).
Per record: post.allowComment: false on a post (or data.allowComment: false on any record) closes it: "Comments are closed on this post." (comment-rules.ts 153). Tested. On the store, Site Config → Storefront → Comments (site.data.storefront.showComments: false) hides the reviews block on product pages (base-app components/storefront/boutique/ProductDetail.tsx 632–637).
What happens to a new comment
In this order (decideOnCreate, comment-rules.ts 178–207):
- Author on the blocked list →
rejected(spam). Tested. - A blocked word →
review, orrejectedwhenblockedWordsActionisreject. Tested both. - More links than
maxLinks→review. Tested: three links were held. after_first_approval, and this person has no approved comment on the site → waits.after_approval→ always waits.- Otherwise
approved: it shows at once. Tested.
"Waits" means new if an AI assistant is picked (the assistant then approves, rejects, hides or sends it to review), else review for a person. With immediately, a picked assistant still checks afterwards and may take it down. An edit by its author goes through the same rules again (decideOnEdit, 214–217). Tested: an edited comment stayed approved and was marked edited.
The writer sees "Thanks — your comment is waiting for approval." for a held comment, and the same words for a rejected one, so a spammer learns nothing (comments.service.ts 424–440). Tested. They also see their own waiting comment in the list, marked "Waiting for approval". Nobody else does.
Who may post, and how
The site's pages call the engine through the site's /api, with the visitor's sign-in when there is one (base-app services/activity-service.ts):
| Call | Who | What |
|---|---|---|
GET comments/<datatype>/<id>?sort=newest&parent=null | anyone | Approved comments with their replies, plus approvedCount and form (open, closedMessage, mayPost: yes / sign_in / guest, reviewsWithRating, reportReasons). Visitors never see emails, reports or moderation notes (buildViews, comments.service.ts 569–629). Tested. |
POST comments/<datatype>/<id> with { message, parentComment?, rating?, title?, name?, email? } | signed-in customer; a guest only when whoMayComment is anyone (name and email then required) | Creates it. Without sign-in on a signed_in site: 401 "Sign in to comment." Tested. Errors: "Add your email to comment.", "Write a comment first.", "Comments are closed on this post." (tested). |
PUT comments/<id> { message, rating, title } / DELETE comments/<id> | its author, or staff | Edit, or remove (kept as deleted). Someone else: 403 "Only its author can change this comment." Tested. |
POST comments/<id>/report { reason: spam / harassment / inappropriate / other, note } | signed in | At reportThreshold reports from different people, an approved comment goes back to review. Tested with three. |
POST stats/comment/<id>/like | signed in | Likes a comment. Without sign-in: 401 "customer is required". Tested. |
A review on a product the writer has a paid order for is marked verified purchase (comments.service.ts 399–403; paid means paid, confirmed, processing, shipped, delivered or completed, line 78).
Ask first
- Which site? The rules are per site; blocked words and people are for the whole business.
- Who may post: only signed-in customers, or anyone with an email?
- When should comments show: at once, after a person's first is approved, or always after approval? Approved by whom: a person, or an AI assistant (which one)?
- Who should be told about new, held and reported comments? Email addresses, or just the owners in the app.
- For a clean-up: which comments (a tab, a post, a product, an author, a word), and what to do with them.
Steps
1. Site Config: read the rules as they are
repo_find on site by data.name, then repo_find_one by its id. Note data.comments exactly as stored (often missing: then every default above applies). Then call_appengine GET comments/settings for blocked words and people.
Hands on: the site sk, its comments block, the blocked lists.
Check: open a post or product on the site as a visitor. A "Sign in to comment" link means signed_in, and a name and email box means anyone.
2. Site Config › Comments: set the rules
Write only the fields that change, with dot paths: call_appengine POST repository/update-partial/site/<sk> with, for example, { "data.comments.showWhen": "after_approval", "data.comments.notify": ["[email protected]"] }. Or use repo_update on site with patch: { "comments": { …the whole block… } }: repo_update merges one level deep, so the whole comments block is replaced, and every field must be in it.
Never send { "data": { … } } to update-partial; the site loses its name, home page and domains. Studio's Comment settings drawer saves the whole site record, so don't save it while another change to the site is being made elsewhere.
For blocked words and people: call_appengine PUT comments/settings with the whole lists ({ "blockedWords": [ … ], "blockedWordsAction": "review", "blockedPeople": [ … ] }). Fields left out keep their value. A blocked person is an email, username or customer id, in any case; an entry starting with @ (@spam.example) blocks a whole email domain (comment-rules.ts 130–138).
Stop: these rules change what visitors see and can post on the live site right away. Show the person the new rules in plain words ("only signed-in customers; every comment waits for you; owners are told"), and wait for yes.
Hands on: the saved comments block.
Check: repo_find_one on the site shows it and the rest of data unchanged. On the site, the comment box matches (sign-in link, or guest fields, or "Comments are turned off on this site.").
3. Comments: read the inbox
call_appengine GET comments/moderation (staff only; tested 403 without sign-in). Query:
| Param | Meaning |
|---|---|
status | tab: review (default), new (new and pending: the AI is still checking), approved, hidden, rejected, deleted, reported (reported and still live), all |
datatype, owner | what it's on: post / sf_product, and that record's sk |
site | the site's sk |
page | the page path or URL it was written on |
classification | spam, harassment, inappropriate, other, clean |
q | words in the message, title, author or page title |
from | written since (ISO date) |
p, ps (max 200), s, st | paging and sort |
Each row has the comment, its statusLabel and decisionLabel, on (title and link of what it's on), the author's history, and actions: the moves allowed now (comment-rules.ts 332–351). The answer also carries the count per tab. Tested. Studio: Comments (/comment), with tabs For review · New & checking · Approved · Hidden · Rejected · Deleted · Reported · All.
GET comments/single/<id> reads one comment in full, with its moderation history and reports, for staff. Anyone else gets what the public list shows: an approved comment, or their own waiting one, without the author's email, the reports or the history; any other id is 404 "Comment not found" (comments.service.ts getCommentView).
Hands on: the ids to act on, and what each one says. Check: the counts match the Studio tabs.
4. Comments: decide
call_appengine POST comments/moderate with { "ids": [ … ], "action": "<action>", "note": "<why>", "classification": "<reason>" }. The answer lists each id with ok and the new status. One failure doesn't stop the rest (comments.service.ts 991–1062). Tested:
| Action | Result |
|---|---|
approve | approved, classified clean, report count back to 0 (reports are kept) |
reject | rejected; classification is harassment, inappropriate or other (default). Anything else: 400 "A reason must be one of: spam, harassment, inappropriate, other." |
spam | rejected as spam |
hide / unhide | off the site, or back on (approved) |
delete (or remove) | deleted: off the site, the record kept. Studio asks for a confirm first, as it does for block_author |
restore | deleted back to approved |
pin / unpin | pinned to the top |
block_author | the author joins the blocked people for the whole business; their next comment is rejected |
Other routes, staff only:
- Reply as the business:
POST comments/<id>/reply{ message }. It is approved at once, markedbyBusiness, and shown under the business's name. Tested. - Set a status directly:
POST comments/<id>/status{ status, classification }. Tested. - Ask the AI again:
POST comments/<id>/recheck. Without a picked assistant: 400 "No AI assistant is picked for this site's comments. Pick one in the site's comment settings." (tested). Held checks are retried every 15 minutes, up to 5 times (comments.jobs.ts).
Stop: every one of these changes what the public sees, or blocks a person from posting anywhere on the business's sites. A reply is published under the business's name. Show the person each comment, the action and (for a reply) the exact words, and wait for yes. For more than a few, show the list.
Hands on: each id's new status.
Check: GET comments/moderation?status=<tab> no longer lists them there. As a visitor, approved ones show on the page and hidden, rejected and deleted ones don't.
5. Reviews and star ratings: what to tell the person
A review's stars are saved on the review (data.rating). They don't add up anywhere:
- Tested: three reviews (5 stars, 9 stars, none) left the product unchanged. Neither its
statsnordata.ratingmoved. - The product page's stars read
data.ratinganddata.reviewsfrom the product (ProductDetail.tsx358–375). Nothing writes those, so they show no average. - Clicking those stars posts to
crm/activity/manage, which doesn't exist (404, tested;build-studio/buttons/button-rating.tsx65). - A separate
POST stats/sf_product/<id>/rating{ value }(signed-in customer) keepsstats.averageRatingandratingCount(appengineanalytics/stats.service.ts229–320). Tested. No page reads it. - Ratings aren't checked: a review of 9 stars was saved (tested). The 1–5 range is only in the schema.
If the person wants an average on the product page today, it has to be worked out and written onto the product. Use aggregate on comment where owner.id is the product, data.status is approved and data.rating is from 1 to 5. Then write update_record_partial on sf_product with { "data.rating": <average>, "data.reviews": <count> }. This is read from the code, not tested. It goes stale with the next review.
Stop: that write changes the live product page. Show the numbers, and wait for yes.
Notifications
Read from code (comments.service.ts 1348–1392; templates in tools/templates/default-email-templates.ts 391–419). Tested only for the in-app case:
| When | Kind | Title |
|---|---|---|
| A comment shows at once | new | "New comment on |
| A comment is held for review (on create, edit, or by the AI) | held | "A comment on |
| Reports reach the threshold | reported | "A comment on |
notifyhas addresses: each one gets an email (comment.<kind>) and an in-app notice (comment.<kind>-notification).notifyis empty: only an in-app notice, to every Owner and ConfigAdmin. Tested: they arrived, and no email went out.- A rejected comment tells nobody.
- The commenter is never told that their comment was approved, rejected or answered.
When it's done
Tell the person:
- the site's rules in plain words: who may post, when comments show, who approves, links and reports limits, closing, and who is told;
- what was decided in the inbox, with counts per action;
- plainly, that review stars don't roll up to the product, and what was done about it, if anything.
Open Comments (navigate to /comment).
What it can't do yet
- No captcha or bot check. The form sends a
recaptchaTokenand Site Config › Spam › Protect comments is saved, but neither is read (comments.service.ts65–75; dbsdkmodels/site.ts622–667). On ananyonesite, a guest is just an email typed into a box. Nothing proves it, so a guest can post as someone else's email, and inherit that person's "already approved" standing underafter_first_approval. - Star ratings don't roll up, the product page stars don't save, and ratings outside 1–5 are accepted (step 5).
- No notice to the commenter, about approval, rejection or a reply.
- Business replies show the business's name, not the staff member's.
allowRatingon a post does nothing; only product comments carry stars.- Delete is soft.
deletekeeps the record asdeleted. Deleting it for good is a repository delete (delete_recordoncomment), which skips the moderation history.
Don'ts
- Don't approve, reject, hide, delete, block or reply without a yes on each comment, or on a list the person has seen.
- Don't send a reply in the business's name with words the person hasn't approved.
- Don't tell the person Protect comments turns on a captcha. It doesn't.
- Don't tell them the product shows an average rating from its reviews. It doesn't.
- Don't write
blockedWordsorblockedPeopleas a partial list: the list you send replaces the old one. - Don't send
{ "data": { … } }toupdate-partialon the site. - Don't test with real customers. Use
@test.local, and delete them after.