Insights & Alerts

Insights are AI-generated narratives about what's changing across your locations — what moved this week, what's risky, what to do next. They live in-app: a card on the main /dashboard and a fuller view on /insights. Alerts are urgent notifications when something needs attention — a sudden rating drop, a sharp review-velocity dip, a fresh negative review, or any custom rule you've set up — and they get delivered as email plus in-app entries on the /insights Alerts panel.

The two systems share a home (/insights) but run on different cadences. Insights are recomputed daily off cached LLM output. Alerts evaluate continuously (review-velocity weekly, agency rollups every 6 hours, negative-review on each review sync) and fan out to email or webhook based on the delivery config you choose.

Reading Insights & Alerts

1. 1

   Open /insights

   Same URL for solo owners and agencies — the page scopes itself to whatever locations you have access to. The top tabs are Overview, Trends, Report Builder, and Alert Builder. The Overview tab is where the AI narrative and the active-alerts panel both live.

2. 2

   Read the AI narrative

   The AIPortfolioSummary card sits at the top of Overview — a short generated paragraph describing how the portfolio (or your single location) moved versus the previous period: top performer, biggest drops, and a one-line risk callout. Below it, AIRisksPanel lists per-location risk items (locationName, pillar, urgency, explanation) and AIActionRecommendations surfaces concrete next steps. Each card stamps generatedAt so you can see how fresh the narrative is.

3. 3

   Look at active alerts

   The Alerts Panel on the same Overview tab shows every open alert across your locations — locationName, pillar (reviews, visibility, engagement, conversions), severity (critical / warning), and the underlying message. Click in to acknowledge, snooze, or resolve.

4. 4

   Configure rules in Alert Builder

   The Alert Builder tab is where you create custom alert rules — pick a metric (review_count, avg_rating, review_velocity, impressions, actions, calls, heatmap_visibility, etc.), a condition (less_than, drops_by_percent, is_zero...), a threshold, the scope (all locations or a specific subset), the schedule (daily / weekly / monthly / realtime), and the delivery channel (in-app, email recipients, optional webhook).

5. 5

   Receive the digest emails

   Built-in alerts ship as email out of the box. Negative reviews arrive per-event as soon as a 1-3-star review syncs in. Review-velocity alerts go out weekly when a location's recent review count drops below its rolling baseline. Agency alert digests batch every active alert across the portfolio into a single email, and the agency weekly summary rolls up portfolio movement plus alertsSummary.newAlerts / resolvedAlerts / criticalCount. Per-location weekly emails default to on and can be disabled per location in AI Settings → Notifications (emailWeeklyReport).

Key Concepts

AI insights — daily narrative, cached for 24h

The Overview narrative, risks list, and recommendations are generated by AgencyInsightsService using GPT-4o-mini. Results are cached in Redis for 24 hours — the getInsights call returns the cached payload until it's stale, then regenerates on the next request. You can also force a rebuild from the page header: the Refresh button hits /api/agency/insights/refresh and ignores the cache. AI insights are a paid action — 5 credits per location (AI Portfolio Insights line on the credit pricing list).

Alert types we fire today

The alerts that actually run on the live cron schedule (see CronManager.ts):

| Alert | Trigger | Email method | | --- | --- | --- | | Negative review | New review with rating ≤ 3 syncs in | sendNegativeReviewAlert | | Review velocity | Weekly check; recent review count below rolling baseline | sendReviewVelocityAlert | | Agency alert digest | Every 6 hours; batches open alerts across the portfolio | sendAlertDigest | | Agency weekly summary | Mondays; portfolio rollup with alerts summary | sendAgencyWeeklySummary | | Custom alert (Alert Builder) | Per-rule schedule (daily / weekly / monthly / realtime) | Routed through AlertDeliveryService (in-app, email, optional webhook) |

The Alert Builder DSL

A custom rule is a (metric, condition, threshold) triple plus a schedule and a delivery config. Metrics span the four pillars — review metrics (review_count, avg_rating, response_rate, review_velocity), visibility (impressions, keyword_impressions, heatmap_visibility, heatmap_avg_rank), engagement (post_count, post_engagement), and conversions (actions, calls, directions, website_clicks). Conditions cover absolute thresholds (less_than, greater_than, equals, is_zero) and period-over-period change (drops_by_percent, increases_by_percent, no_change). Scope is either all locations under your account or a specific list.

Digest cadence vs. real-time

Real-time (negative_review, realtime custom rules) fires as soon as the underlying event is processed — usually within the next sync cycle. Weekly (review_velocity, agency_weekly_summary, weekly custom rules) fires on Mondays. Periodic (agency_alert_digest, custom_alerts evaluation) runs every 6 hours. Daily AI insights rebuild on the first request after the 24-hour cache expires. Anything configurable lives in the per-rule schedule on /insights → Alert Builder, or per-location in AI Settings → Notifications.

Agency weekly summary vs. alert digest

Two distinct emails for agency users:

• Agency alert digest (sendAlertDigest) — a flat, batched list of open alerts: total / critical / warning counts plus each alert's locationName, pillar, severity, and message. Good for "one digest per cycle" mode.
• Agency weekly summary (sendAgencyWeeklySummary) — a Monday rollup of totalLocations, impressionsChange, actionsChange, top performer, the "needs attention" list, and alertsSummary.newAlerts / resolvedAlerts / criticalCount. This is the executive-style email; the alert digest is the operational one.

Frequently Asked

Related