Overview: The Red Flag Alert System automatically monitors all incoming reviews and comments to detect critical issues that require immediate management attention. The system uses keyword matching, AI sentiment analysis, and pattern detection to identify reviews that could pose legal, reputational, or operational risks.

What are Red Flags?

Red flags are reviews or comments that contain specific indicators of serious problems such as safety concerns, legal threats, discrimination claims, or coordinated attacks. The system categorizes these into different alert levels based on urgency.

Alert Levels:

Level 1: CRITICAL (Red) - Immediate Action Required

• Safety & Health Concerns: Physical harm mentions (injury, fell, blood, emergency room, hospital), health hazards (food poisoning, sick, nausea, rats, pests, mold), illegal activity (theft, drugs, harassment, assault, police)

• Legal & Regulatory Threats: Litigation threats (lawyer, lawsuit, suing, legal action, small claims court), fraud accusations (scam, fraud, ripoff, stolen money, false advertising)

• Review Bombing: Multiple 1-star reviews (default: 5+) received within a short time window (default: 60 minutes), indicating a potential coordinated attack

Response Time: Within 1-4 hours. These issues can escalate quickly on social media or lead to legal liability.

Level 2: WARNING/URGENT (Orange) - Management Required

• Personal Attacks & Staff Mentions: Reviews identifying specific employees by name or description ("the lady with red hair", "employee named John", "manager"), discrimination claims (racist, sexist, homophobic, prejudice)

• Service Friction Signals: Frustration language (for example "eish", "yoh"), service delay wording ("waited too long", "long wait"), and 3-star-without-text patterns can be routed to Needs Attention for follow-up

• Influencer Reviews: Reviews from accounts with high follower counts (default: 50,000+ followers), as negative reviews from influencers can have outsized impact

Response Time: Within 4-24 hours. These require careful HR consultation and strategic response planning.

Level 3: ATTENTION (Yellow) - Brand Attention Needed

• Competitor Mentions: Direct competitor name mentions ("Go to [Competitor] instead", "much better than [You]"), comparative statements that damage your brand positioning

• SEO & Brand Integrity: Brand name misspellings, misuse of sub-brands, defamatory brand references

Response Time: Within 24-48 hours. These affect your brand perception and search rankings.

Insight (Green) - Positive Opportunity: Positive local sentiment cues (for example "lekker", "shot", "friendly staff") can generate an AI thank-you draft suggestion without escalating to a red flag.

Detection Methods:

1. Keyword Monitoring:

The system maintains a database of flagged keywords organized by category and alert level. Detection is intent-first: low-signal generic terms are suppressed, while legal/fraud/safety/staff-harm signals are prioritized for escalation.

2. AI Sentiment Analysis:

For Critical and Urgent level alerts, the system uses GPT-4o-mini to analyze the review context and provide:

• Overall sentiment classification (positive/negative/neutral/critical)

• Severity assessment (critical/high/medium/low)

• Detailed explanation of why the review is concerning

• Recommended response approach

3. Pattern Detection:

Review Bombing Detection: The system tracks the volume and timing of negative reviews per location. If the threshold is exceeded (e.g., 5 one-star reviews in 60 minutes), a Critical alert is triggered even if individual reviews don't contain flagged keywords.

Influencer Detection: When review metadata includes follower count, the system automatically escalates reviews from accounts exceeding your configured threshold.

How Alerts Work:

Automatic Detection: All reviews and comments are automatically scanned as they arrive. The system runs in real-time using database triggers, so alerts are created within seconds of a review being posted.

Multiple Notification Channels:

• In-App Notifications: Alerts appear in your dashboard notification center

• Email Alerts: Immediate email sent to configured recipients (configured in Settings)

• Webhook/CRM Integration: POST request sent to your webhook URL with alert details

Alert Dashboard: Navigate to Dashboard > Red Flags to view all alerts. The dashboard shows:

• Summary statistics (total alerts, breakdown by level, unresolved count)

• Filterable list of all alerts with full details

• Quick actions to mark alerts as resolved

• Links to view the location and original review

Account Scope Behavior: For admin, customer, customer_manager, and campaign_specialist users, Red Flags respects the same organization Account Sync Scope used in Admin settings. Alerts for out-of-scope accounts are excluded from the list, and those alerts cannot be resolved via API by these roles.

Email Notifications:

When enabled, critical alerts trigger immediate email notifications to your configured recipient list. The email includes:

• Alert level and category clearly labeled

• Full review text with flagged keywords highlighted

• Reviewer information including follower count if applicable

• AI analysis explaining the concern

• Direct link to view and respond in your dashboard

CRM Integration via Webhook:

For organizations using external CRM or ticketing systems, ProfilePilot can send alerts to your webhook endpoint. The webhook receives:

• Alert ID and metadata

• Review content and platform

• Alert level and category

• Matched keywords and AI analysis

• Location information

Public API Endpoint: Use GET `/api/red-flags/webhook` with your API key to retrieve alerts programmatically. Query parameters:

• `since`: ISO timestamp to get alerts since a specific time

• `level`: Filter by alert level (red/orange/yellow)

• `resolved`: Filter by resolution status (true/false)

Mark Resolved via API: POST to `/api/red-flags/webhook` with your API key and alert ID to mark an alert as resolved from your external system.

Configuration:

Navigate to Dashboard > Red Flags > Settings to configure the alert system:

Enable/Disable: Toggle the entire red flag system on or off

Email Alerts:

• Enable/disable email notifications

• Add multiple recipient email addresses

• Emails are sent for all Critical and Urgent alerts

Webhook Integration:

• Enable/disable webhook notifications

• Configure your webhook endpoint URL

• Webhooks receive JSON payload with all alert details

Detection Thresholds:

• Review Bombing: Set the number of negative reviews and time window (default: 5 reviews in 60 minutes)

• Influencer Threshold: Set minimum follower count for influencer alerts (default: 50,000)

Custom Keywords: Add organization-specific keywords to monitor (e.g., internal product names, local competitor names)

Intent Phrase Tuning: In Red Flags Settings, admins can tune organization-specific phrase lists for Critical, Warning, Insight, and suppressed low-signal keywords. This allows local-language tuning (for example South African phrasing) and reduces false positives from generic terms.

Manual Resolution Workflow: Posting a review response does not auto-resolve a red flag. Alerts remain open until a user marks them resolved, so response and risk-closure are tracked separately.

Best Practices:

• Review Critical Alerts Immediately: Red-level alerts indicate serious issues that can escalate quickly

• Have a Response Protocol: Create an internal escalation process for each alert level

• Multiple Email Recipients: Add several team members to ensure alerts are seen even if someone is unavailable

• Test Your Webhook: Use the test button in settings to verify your webhook integration is working

• Monitor Patterns: Review resolved alerts weekly to identify recurring issues

• Update Thresholds: Adjust review bombing thresholds based on your typical review volume

• Document Resolutions: Use the resolution notes field to track how each alert was handled

• HR Coordination: For staff mention alerts, coordinate with HR before responding publicly

• Legal Review: Consult legal counsel for alerts involving threats or fraud accusations before responding

Common Questions:

"Are all negative reviews flagged?"

No. Only reviews containing specific red flag indicators are flagged. Regular negative reviews appear in your normal Reputation dashboard.

"Can I customize the keywords?"

Yes. In Settings > Red Flags, you can add custom keywords specific to your business or industry.

"What if I get too many false positives?"

Adjust your detection thresholds and review bombing settings. You can also disable specific alert categories if they're not relevant to your business.

"Can I turn off alerts for specific locations?"

Currently, alerts apply organization-wide. Contact support if you need location-specific configuration.

"Do alerts work for all platforms?"

Yes. The system monitors Google Business Profile, Meta (Facebook), and all other connected review platforms.

"What happens if I miss an alert?"

All alerts remain in the dashboard until marked as resolved. Email notifications are sent immediately, and you can set up webhook integration for additional redundancy.

Getting Started:

1. Navigate to Dashboard > Red Flags > Settings

2. Enable red flag monitoring

3. Add email recipients for alerts

4. Review and adjust detection thresholds

5. (Optional) Configure webhook URL for CRM integration

6. Click "Save Configuration"

7. Test the system by checking the Alert Level Guide in settings

Understanding Your API Key:

To use the webhook API endpoint, you'll need your organization's API key:

• Found in Settings > Integrations > API Access

• Include in requests as X-API-Key header

• Keep this key secure - it grants access to your alert data

• Regenerate if compromised

Example Webhook Payload:

When an alert is triggered, your webhook receives:

```json

{

"event": "red_flag_alert",

"alert_id": "uuid",

"alert_level": "red",

"category": "safety_health",

"location_id": "ChIJ...",

"platform": "google",

"reviewer_name": "John Doe",

"review_text": "...",

"review_rating": 1.0,

"matched_keywords": ["injury", "fell"],

"ai_analysis": "Customer reports physical injury requiring immediate attention",

"created_at": "2026-01-12T10:30:00Z"

}

```

Your CRM can parse this payload to create tickets, send notifications, or trigger automated workflows.