Reseñas

Lee, responde y analiza reseñas, competidores, widgets y fuentes de reseñas.

• Readget_reviews_rollupSummary of all reviews across locations: total count, average rating, unreplied count, positive percentage, sentiment trends, response rate, new reviews and velocity change, best and worst locations by health, per-location breakdown with ratings distribution and top themes. Use for reputation overview, review analysis, trending, performance comparison.
• Readlist_reviewsList reviews for a location across all platforms: author, rating, text, date, sentiment, topics, whether replied. Filter by platform, rating, sentiment, date range. Use for review analysis, finding unanswered reviews.
• Readget_review_statsReview statistics for one location: total reviews, sentiment breakdown (positive/neutral/negative), average rating, response rate, per-platform breakdown (Google, Yelp, TripAdvisor, Facebook). Use for reputation analysis, review performance, rating trends.
• Readget_review_analyticsDeep-dive review analytics for a location: KPI cards with change vs prior period, reviews over time, sentiment trends, response rate trends, top themes. Use for reputation trending, sentiment tracking.
• Writereply_to_reviewPost or update the owner reply to a single review. Pushes live to Google/Facebook. Pass draft=true to save it as an UNSENT draft for approval instead — nothing reaches the publisher, `pushed` is false and `drafted` is true; use it when a person should review the reply first (the app's own reply box and bulk flow do the same). In a client-portal session every reply is a draft regardless.
• Writedelete_review_replyDelete the owner reply to a single review, keyed by reviewId (from list_reviews). For Google and Facebook the reply is removed live on the publisher (Facebook deletes the Page comment); deleting a reply that is already gone still succeeds (idempotent). Only reviews on platforms that support delete (Google and Facebook today) can be deleted. In OS this is an archive, not a row delete — the record is kept internally (marked archived) even though it's genuinely gone from the publisher's page. Returns { ok, pushed } — whether it reached the publisher.
• Writeadd_review_noteAdd an internal staff note to a single review, keyed by reviewId (get it from list_reviews). Notes are agency-internal — never shown to the client. Tenant-scoped: a review outside the caller's agency is rejected. Empty or over-4000-char bodies are rejected. Returns the created note. @-mentions are not supported (mentions stay empty).
• Readlist_review_notesList the internal staff notes on a single review, newest-first, keyed by reviewId. Agency-internal — never client-facing. Tenant-scoped: a review outside the caller's agency is rejected. Returns { notes: [{ id, body, authorUserId, authorName, createdAt }] }.
• Writedelete_review_notePermanently delete an internal staff note from a review. Identify it by reviewId (from list_reviews) and noteId (from list_review_notes). Tenant-scoped: a review outside the caller's agency is rejected. A note that's already gone (wrong id, or already deleted) is not an error — check the returned `deleted` count rather than assuming.
• Readget_competitor_analyticsCompare reviews against tracked competitors: benchmark scores, rating comparison, review volume, sentiment gap, strengths/weaknesses. With clientId and locationId it is one location against its competitors; with clientId alone it is the whole client (all its locations) against the client-wide roll-up competitors. The result says which (`scope`). Use for competitor comparison, competitive analysis.
• Readlist_competitorsList competitors tracked for a location — or, with only clientId, for the whole client (the roll-up competitors shown across all its locations, the ones add_client_competitor creates): name, rating, review count, sentiment. The result says which (`scope`: location | client). Use for competitor lookup, competitive landscape.
• Readget_competitorGet one tracked competitor's profile (rating, review count, sentiment, etc.). Pass competitorId (from list_competitors) with clientId and locationId for a location's competitor, or with clientId alone for a client-wide roll-up competitor.
• Writeadd_competitorTrack a new competitor for a location, by business name (matched to Google). Location-scoped — requires clientId, locationId, name. Returns the created competitor profile.
• Writeadd_client_competitorTrack a new competitor at the CLIENT level (a roll-up competitor shown across every location for that client), by business name. Distinct from add_competitor, which tracks one for a single location. Returns the created competitor profile.
• Writerefresh_client_competitorsTrigger competitor auto-discovery and a fresh review pull across an entire client (every one of its locations), rather than one already-tracked competitor. Runs in the background — discovery plus a deep review pull can take longer than a single request allows for a large client. Returns { ok, queued }; there is no synchronous result to check.
• Writeremove_competitorStop tracking a competitor, by competitorId (from list_competitors). Agency-scoped.
• Writerefresh_competitorRe-scrape a single tracked competitor's Google reviews, by competitorId (from list_competitors). Returns { ok, note }.
• Readget_topic_trendsWhat customers talk about: topic leaderboard with mentions and sentiment, rising and declining themes, emerging topics. Use for customer feedback analysis, review themes, what's trending in reviews. Pass locationId for ONE location; omit it for the CLIENT-WIDE roll-up across all the client's locations (optionally only those carrying `tag`) — the same numbers the Reviews page shows, with the locations' reviews pooled, so a location with more reviews weighs proportionally more. The result says which (`scope`: location | client). For a client roll-up windowDays is 30, 90 or 180.
• Readget_topic_seriesTopic trends over time — the per-topic monthly sentiment/mention series behind the Topic Trends heatmap. Pass locationId for one location; omit it for the client-wide roll-up across all the client's locations (optionally only those carrying `tag`), with their reviews pooled so a location with more reviews weighs proportionally more. The result says which (`scope`: location | client). Optional months (default 12; 1-24 for a roll-up).
• Readget_topic_reviewsList the reviews that mention a specific topic for a location (drill-down from get_topic_trends). Location-scoped — requires clientId, locationId, and topic. Optional month (YYYY-MM) narrows to a single month — pass it when the caller is drilling into ONE cell of the topics-by-month heatmap, or you get the topic's whole history newest-first instead of that cell's reviews. Optional limit (default 50).
• Readlist_review_widgetsList the review widgets configured for a location (embeddable review displays for the client's website). Location-scoped — requires clientId AND locationId.
• Readget_review_widgetGet a single review widget by id (its config + status). Agency-scoped.
• Readcount_widget_matchesCount how many of a location's reviews match a widget configuration — the live '{N} reviews match this configuration' preview. Location-scoped — requires clientId AND locationId. Optional minRating, sources, includeInternal, dateWindow (30d | 90d | 1y | all).
• Writecreate_review_widgetCreate an embeddable review widget for a location. Location-scoped — requires clientId, locationId, name. Optional: minRating, sources, selectionMode (recent | highest | rotate | manual | ai), dateWindow (all | 6m | 12m), count (1–50), includeInternal, layout (carousel | marquee), status (draft | published, default published). Use count_widget_matches first to preview how many reviews match.
• Writeupdate_review_widgetEdit an existing review widget in place: the same widget (same id, same embed URL) with new settings, so a site that already embeds it picks up the change. Pass widgetId (from list_review_widgets) and only the fields to change. Fields: name, minRating (1–5, or null for none), sources (marketplaces; empty = all), selectionMode (recent | highest | rotate | manual | ai), dateWindow (all | 6m | 12m), manualReviewIds, count (1–50), includeInternal, emojiPositiveRating (1–5), layout (carousel | marquee), marqueeSpeed (1–10), theme (brand | white | dark), themeOverrides, showFlags (avatar/date/rating/reply/sourceLogo/header/cta true|false), status (draft | published — draft stops it rendering publicly). At least one field is required; unknown or out-of-range values are rejected. Returns the updated widget. Use count_widget_matches to preview how many reviews a filter change matches.
• Writedelete_review_widgetDelete a review widget by id. Agency-scoped.
• Readget_invite_rollupReview-request performance across a client's locations in one read: the acquisition funnel (sent → delivered → clicked → responded), Email-vs-SMS effectiveness, deliverability (bounces, unsubscribes and the worst locations), locations needing attention, and a per-location table with response rate and average rating. Use it for "how are our review requests doing?" instead of walking every location's campaigns. Pass clientId (from list_clients) to scope to one client — omit for the whole agency — and optionally one internal tag (from list_location_tags) to narrow to locations carrying it. Window: pass both from and to (ISO dates), or neither for the last 90 days. Counts recipients actually sent in the window; the portfolio figures are computed from summed counts, not by averaging per-location rates.
• Readlist_review_campaignsList a location's review-acquisition campaigns (email/SMS review requests). Location-scoped — requires clientId AND locationId. Paginated.
• Readget_invite_statsGet review-invite acquisition stats for a location: total acquisitions, feedback received, customer-experience score, click-through rate. Location-scoped — requires clientId AND locationId.
• Readlist_campaign_responsesList responses to a location's review-invite campaigns (who responded, feedback given). Location-scoped — requires clientId AND locationId. Paginated.
• Readlist_campaign_recipientsList recipients of a location's review-invite campaigns (contacts messaged + delivery/response status). Location-scoped — requires clientId AND locationId. Paginated.
• Readget_campaignGet a single review-invite campaign by id (config, status, schedule). Agency-scoped.
• Writebulk_reply_reviewsPost replies to many reviews in one call. Pass `replies` as an explicit array of { reviewId, text }. Each is applied independently (Google and Facebook pushed live; others saved). Rate-limited per Google Business Profile (10 edits/min); throttled items come back with retryable:true so they can be re-attempted rather than treated as hard failures. Returns a per-review result array with ok/pushed/error/retryable, plus succeeded/failed counts. Pass draft=true to save EVERY reply as an unsent draft for approval instead (nothing reaches the publisher; `drafted` is true and `pushed` false throughout) — the bulk flow in the app works this way. IN A CLIENT-PORTAL SESSION every reply saves as an unsent DRAFT and none reaches the publisher — `pushed` is false throughout and the agency sends them. Report them as drafted, never as posted.
• Readlist_review_sourcesList every review source configured for a location: the automatically-pulled platforms (Google, Facebook, …) and any custom review-page URLs added with add_review_source. Hidden sources and sources with no reviews yet ARE included — those are the ones you need to find again to unhide or remove. Each row has its key, id (custom sources only), platform, label, url, whether it is hidden, how many reviews it holds, its fetch status and next fetch, and allowedActions (hide / unhide / remove). Use the row's id as sourceId for remove_review_source, and its key plus type (auto | custom) for hide_review_source. Location-scoped — requires clientId AND locationId.
• Readvalidate_review_sourceCheck whether a URL is a usable review source before adding it with add_review_source. Probes the page live (a few seconds), detecting its platform (Google/Yelp/Facebook/TripAdvisor/Trustpilot/BBB/Foursquare/Healthgrades/OpenTable/custom), whether it actually collects reviews, an estimated review count, and the business name found on the page. If you pass locationId, it also checks whether the page's business name matches that location's name and whether this URL is already added there; omit locationId to instead get a suggested location match by name. `ok` is true only when the source collects reviews AND isn't a duplicate.
• Writeadd_review_sourceAdd a custom review source (a specific review-page URL) to a location — e.g. a Yelp, TripAdvisor, Trustpilot, BBB, or other business-listing page whose reviews aren't already pulled in automatically (Google and Facebook are auto-pulled via the connected OAuth account and don't need this). Run validate_review_source on the URL first to confirm it collects reviews and isn't already added. Once added, its reviews are scraped immediately in the background and then re-checked on a recurring schedule. Fails if this exact URL is already added to this location.
• Writehide_review_sourceHide or unhide a review source from a location's review feed and analytics, without deleting its historical reviews. Pass an auto-detected platform slug (e.g. "google") with type "auto" to hide one of the automatically-pulled platforms, or a custom source's id (from validate_review_source's result, or the id returned by add_review_source) with type "custom".
• Writeremove_review_sourcePermanently remove a custom review source from a location. This only removes the tracked source going forward — reviews already imported into the app from it are NOT deleted. Only custom sources (added via add_review_source) can be removed this way; the auto-pulled platforms (Google, Facebook) can only be hidden with hide_review_source, not removed. Identify the source by its sourceId (from add_review_source's result, or a "custom:<id>" key seen elsewhere).
• Readget_review_keyword_settingsRead custom and hidden review topics, including hidden keywords and their counts. Provide either locationId or clientId for its roll-up. Requires an active agency user with Reviews and owning-client access.
• Writeadd_review_keywordTrack a custom review topic for either a locationId or clientId. Up to 10 custom keywords; 3–128 characters. Saves it and requests background semantic tagging, which can use generation capacity. Counts fill in later. Check queued/warning before claiming tagging started. Requires Reviews and owning-client access.
• Writeremove_review_keywordRemove a custom review topic and its tags for either locationId or clientId. Preserves the reviews. Requires an active agency user with Reviews and owning-client access.
• Writeset_review_keyword_hiddenHide or unhide a review topic without removing the reviews or custom-keyword configuration. Provide either locationId or clientId and an explicit hide boolean. Requires Reviews and owning-client access.
• Writeupdate_review_source_intervalChange a custom review source's recurring collection interval to 6, 12, 24 or 168 hours. Changes future collection frequency and associated usage. Requires Reviews and access to the source's owning client.
• Writeretry_review_sourceReset an active custom review source and request another fetch. Never re-enables disabled or removed sources. Collection can consume provider usage. Returns queued:false with a warning if immediate enqueueing failed; the scheduled retry remains enabled. Requires Reviews and owning-client access.
• Writedraft_bulk_review_repliesSave the same reply text as an UNSENT draft for up to 50 reviewIds. Never publishes. Checks access to every review before writing, then returns a per-review outcome plus succeeded/failed counts. Some drafts may succeed while others fail; inspect results before retrying. Requires an active agency user with Reviews and access to every owning client.