Reviews & UGC

Zubby can store product-review text and retrieve relevant snippets when a shopper asks a product-specific question. This page explains the supported ingestion contract, the Growth plan gate on review-grounded answers, and the separate merchant feedback and conversation queues.

The Reviews hub has three tabs: AI feedback, Product reviews and Moderation queue. Each answers a different question:

Product reviews (UGC the agent cites)

This is the page most merchants mean by “reviews.” Open Reviews → Product reviews. It’s a read-only viewer over the reviews Zubby has ingested, so you can see exactly what’s in the corpus the AI quotes from.

Where reviews come from

The current application accepts authenticated review payloads at the reviews-ingestion endpoint. A platform plugin, provider automation, or custom adapter must send the data; Yotpo, Judge.me, and Stamped are not native pull connectors in the current integration registry. Supported source labels are:

• Yotpo
• Judge.me
• Stamped
• Native - reviews already attached to your store.

Each ingested review stores its rating, title, body, author, verified- buyer flag, source, language, the linked product, and the original external timestamp.

What the page shows

Three summary cards sit up top:

• Total reviews - overall count, with how many are from verified buyers.
• Average rating - mean stars across every source.
• Sources - how many providers are feeding reviews, listed by name.

Below that you can filter by rating (1–5 stars) and by source, then browse the latest 50 reviews - newest external timestamp first. Each row shows the star rating, a source badge, a verified-buyer badge where applicable, the language, the review title and body, the author, and a link to the product’s catalog detail page.

Getting reviews into the corpus

1. Configure a trusted platform or provider adapter to send authenticated payloads to /api/v1/webhooks/reviews. Use the store’s server-side plugin credential; never expose it in storefront code.
2. Send a small controlled batch and check the Sourcescard, counts, linked products, timestamps, and representative text.
3. Filter to 1–2 star reviews and skim them: the agent can cite these too, so you want to know what shoppers will hear about weak spots.
4. Ask the widget a quality question (“how do these fit?”) and inspect the returned review evidence. Review-grounded answers require the Growth entitlement.

Review-grounded answers

On the Growth plan and above (the Reviews module), the AI can answer “is it good?”, fit, sizing, comfort, and durability questions from what real buyers said about one product. It works in the widget and on connected messaging channels. For that product it can cite:

• The average rating with its rating count, for example “4.6 out of 5 from 212 ratings”. Ratings come from the reviews you ingest, or from your WooCommerce product rating when that covers more ratings.
• The themes buyers praise and complain about, from Zubby’s summary of the product’s reviews.
• Up to three short verbatim quotes, never with the reviewer’s name. A review that contains an email address, phone number, card-like number, link, or @handle is skipped rather than quoted.

The AI is instructed to use only retrieved ratings. Review answers for accuracy. When a product has no reviews, it is instructed to say nothing about reviews, unless the shopper asked about them directly, in which case it says there are none yet. Reviews are buyer opinions: your store policies, locked facts, and product specs always win, so a review is never used to state a return window, warranty, shipping promise, ingredient, or health or safety claim. With the Reviews module on, ratings also appear next to products the AI finds in search.

Snippets in product answers

The product-question tool performs a bounded lexical lookup over review bodies for the selected product and returns up to five real snippets. When no keyword match exists it falls back to recent verified-buyer reviews. The model must still interpret that evidence correctly; review text can be subjective, stale, or irrelevant to the shopper.

Reviews & Feedback (ratings on AI answers)

Separate from product reviews, Reviews & Feedback (sidebar: AI Training → AI Feedback) aggregates the labels your team records on AI messages from the conversation view: good, incomplete, wrong, or needs handoff. It is read-only; you act from the linked conversation or the feature that owns the root cause.

It shows:

• Total feedback, with the change versus the prior 7 days.
• Positive (good) and Negative (wrong or incomplete) percentages and counts.
• 7-day volume of ratings.
• A recent feedback list - each entry quotes the rated message, shows who left it, and deep-links to the full conversation.
• Negative themes - common words pulled from negative- feedback notes, so repeated complaints stand out.

The intended workflow: spot a recurring negative theme, open the conversation for context, classify the root cause, then fix the owning knowledge, catalog, rule, tone, tool, or handoff configuration and replay the scenario.

Review Queue (conversation moderation)

Review Queue surfaces whole conversations the AI might have mishandled so you can flag them for retraining. It’s about chat quality, not product reviews. Filter chips narrow the list to:

• Low CSAT - conversations rated 2/5 or lower.
• Negative sentiment - flagged negative by the agent.
• Low confidence - confidence score at or below 0.4.
• Escalated - handed off to a human.

Each card shows the conversation summary, CSAT, sentiment, and confidence badges, plus a link to open the full thread. Use it as a recurring QA triage surface. The default view includes recent conversations that do not match a risk filter, so select a filter when prioritizing likely failures.

Gotchas

• No product reviews showing? Verify the authenticated ingestion request, store credential, source label, product platform ID, response body, and inserted count. Text-review ingestion is an API write; it is not the Loox background pull.
• Choose the right tab. Product reviews contains product opinions; AI feedback contains answer ratings; Moderation queue contains flagged conversations.
• Edit reviews at the source. Zubby mirrors the provider payload. Correct reviews and replies at the source, but do not expect resending the same source and external ID to update the stored review. This ingestion contract is insert-only and exposes no update or deletion endpoint. Contact support about a correction to an already ingested record; do not create duplicate IDs to simulate an update.

Related

• Catalog & product sync - reviews link back to product detail pages.
• Product recommendations - social proof shown alongside suggestions.
• Knowledge base - turn recurring negative feedback into permanent fixes.
• API reference - authentication and integration conventions for server-side adapters.

Developer example: insert one synthetic review

This server-side endpoint uses the store plugin Bearer credential and X-Store-ID, not a public read API key or browser widget key. Review ingestion and review-grounded answers require the reviews entitlement. Keep credentials on your server.

POST /api/v1/webhooks/reviews
Authorization: Bearer SERVER_SIDE_STORE_CREDENTIAL
X-Store-ID: YOUR_STORE_ID
Content-Type: application/json

{"reviews":[{"source":"native","externalReviewId":"example-review-001","platformProductId":"example-product-42","rating":4,"body":"The strap is comfortable for short walks.","verifiedBuyer":false,"language":"en","createdExternalAt":"2026-10-20T12:00:00Z"}]}

Send one review object or a reviews array of at most 100. Source and platformProductId are required; rating, text and externalReviewId are optional. Use a stable externalReviewId to deduplicate. A successful first insert can return {"ok":true,"processed":1,"inserted":1}. Reposting the same source and external ID inserts nothing; this is insert-only, not an update API. No update or deletion endpoint is provided by this contract.

Invalid authentication returns 401 or the authentication error status; missing entitlement returns 402; invalid payload returns 400. A 200 response can still have fewer inserted than processed, so compare both counts and inspect the Product reviews tab. Verify the product ID matches your catalog before testing retrieval. These examples are synthetic and are not customer proof.

Why a tab may be missing

AI feedback needs the Training permission. Product reviews needs Growth access and the reviews plan entitlement. Moderation queue needs both Training and Catalog permissions because it can flag conversations and review product Q&A. Ask a store owner or admin to review permissions if the hub redirects to another tab.