Developer Handover Pack

Developer Handover Pack

Review and Reputation Management

Reads each incoming review record and assigns a sentiment category (positive, neutral, or negative), a confidence score between 0 and 1, and a concise one-line topic summary. Its output fields determine which downstream branch the workflow follows: positive and neutral reviews proceed directly to the Response Drafting Agent, while negative reviews (two stars or below) trigger the Slack escalation path. This agent must handle all supported platform formats and gracefully degrade when review text is very short (under 10 words) or in a non-English language.

// Input
platform: string          // 'google_business_profile' | 'trustpilot'
reviewer_name: string     // May be 'Anonymous' on some platforms
star_rating: integer      // 1-5
review_text: string       // Raw review body
review_id: string         // Platform-native unique ID (dedup key)
review_timestamp: string  // ISO 8601

// Output
sentiment: string         // 'positive' | 'neutral' | 'negative'
confidence_score: float   // 0.00-1.00
topic_summary: string     // Max 20 words, plain English
is_negative_flag: boolean // true if star_rating <= 2
notion_row_id: string     // ID of newly created Notion tracker row
classification_timestamp: string // ISO 8601

Generates a contextually appropriate reply for each review using the sentiment classification, star rating, review text, and brand voice guidelines stored in the agent's system prompt. Positive and neutral reviews receive an auto-approved draft that proceeds immediately to posting. Negative reviews (is_negative_flag: true) receive a draft that is packaged into a Slack message to the designated manager channel along with an approval link. The agent must not post any response autonomously for negative reviews under any circumstance. Brand voice guidelines must be loaded into the system prompt from a versioned source (a Notion page or a static prompt file in the credential store) so they can be updated without a code change.

// Input
sentiment: string          // From Review Classifier Agent output
star_rating: integer       // 1-5
review_text: string        // Raw review body
topic_summary: string      // From classifier
is_negative_flag: boolean  // Routing gate
notion_row_id: string      // For status update after action
platform: string           // Determines posting method
reviewer_name: string      // Used in response personalisation

// Output (positive/neutral path)
draft_response: string     // Brand-voice reply, max 300 characters
post_status: string        // 'posted' | 'failed'
posted_at: string          // ISO 8601
notion_row_id: string      // Passed to CRM and Reporting Agent

// Output (negative path — Slack escalation)
draft_response: string     // Draft included in Slack message
slack_message_ts: string   // Slack message timestamp (for threading)
approval_link: string      // Deep link to approval action
approval_status: string    // 'pending' | 'approved' | 'rejected'

// On approval (negative path, after manager action)
post_status: string        // 'posted' | 'failed'
posted_at: string          // ISO 8601
approved_by: string        // Slack user ID of approving manager
notion_row_id: string      // Passed to CRM and Reporting Agent

Matches the reviewer to an existing HubSpot contact using name and email where available, then logs the review outcome as a timeline activity on the matched contact record. For anonymous reviews or platforms that mask reviewer details, the agent creates a partial record flagged for manual enrichment rather than skipping the step entirely. Additionally, every Monday at 08:00 local time this agent queries the Notion tracker for the prior week's data, compiles a reputation summary, and posts it to the designated Slack channel. The reporting function is time-triggered and independent of the per-review flow.

// Input (per-review trigger)
notion_row_id: string      // Completed review row
reviewer_name: string      // Used for HubSpot contact search
reviewer_email: string     // May be null for anonymous reviews
platform: string
star_rating: integer
sentiment: string
post_status: string        // Must be 'posted' to proceed
posted_at: string          // ISO 8601
approved_by: string        // Slack user ID or null for auto-posted

// Input (weekly schedule trigger)
report_week_start: string  // ISO 8601 date, Monday
report_week_end: string    // ISO 8601 date, Sunday

// Output (per-review)
hubspot_contact_id: string // Matched contact ID or 'partial_record_created'
hubspot_activity_id: string // Timeline activity ID
notion_row_updated: boolean // True when ResponseStatus set to 'posted'

// Output (weekly report)
slack_report_ts: string    // Slack message timestamp
report_summary: object     // { total_reviews, avg_rating, response_rate_pct,
                           //   sentiment_breakdown: {positive, neutral, negative},
                           //   top_complaint_themes: string[] }

// ============================================================
// REVIEW AND REPUTATION MANAGEMENT: END-TO-END DATA FLOW
// ============================================================

// TRIGGER: Scheduled polling (every 15 minutes)
// Source: Google Business Profile API + Trustpilot API
// Fields captured at trigger:
platform          = 'google_business_profile' | 'trustpilot'
reviewer_name     = string   // e.g. 'Jane Smith' | 'Anonymous'
star_rating       = integer  // 1-5
review_text       = string   // Raw review body
review_id         = string   // Platform-native UID (dedup key)
review_timestamp  = string   // ISO 8601

// DEDUP CHECK: Query Notion tracker for existing review_id + platform
// If match found -> log duplicate_skipped, end workflow
// If no match -> continue

// ============================================================
// AGENT HANDOFF 1: Trigger -> Review Classifier Agent
// Fields passed: platform, reviewer_name, star_rating,
//                review_text, review_id, review_timestamp
// ============================================================

// REVIEW CLASSIFIER AGENT processing:
sentiment            = 'positive' | 'neutral' | 'negative'
confidence_score     = float    // 0.00-1.00
topic_summary        = string   // Max 20 words
is_negative_flag     = boolean  // true if star_rating <= 2

// ACTION: Write classified record to Notion tracker
// Notion DB properties written:
notion_row_id        = string   // Returned by Notion API on create
Platform             = platform
ReviewerName         = reviewer_name
StarRating           = star_rating
ReviewText           = review_text
Sentiment            = sentiment
ConfidenceScore      = confidence_score
TopicSummary         = topic_summary
IsNegative           = is_negative_flag
ResponseStatus       = 'pending'
ReviewID             = review_id
CreatedAt            = review_timestamp

// ============================================================
// AGENT HANDOFF 2: Review Classifier Agent -> Response Drafting Agent
// Fields passed: sentiment, star_rating, review_text,
//                topic_summary, is_negative_flag, notion_row_id,
//                platform, reviewer_name
// ============================================================

// RESPONSE DRAFTING AGENT processing:
// Load brand voice guidelines from Notion config page at runtime
draft_response = string  // Max 300 chars, platform-appropriate tone

// BRANCH A: is_negative_flag == false (positive or neutral)
//   -> Post response directly to platform
//   -> GBP: My Business API v4.9 'accounts.locations.reviews.updateReply'
//   -> Gmail API: 'users.messages.send' for email-reply platforms
post_status      = 'posted' | 'failed'
posted_at        = string   // ISO 8601
//   -> On failure: retry x3 (30s/60s/120s), then alert ops Slack channel
//   -> Update Notion row: ResponseStatus = 'posted'

// BRANCH B: is_negative_flag == true (2 stars or below)
//   -> Send Slack Block Kit message to manager channel
slack_message_ts   = string  // For threading
approval_link      = string  // Interactive component action URL
approval_status    = 'pending'
//   -> Manager clicks Approve:
approved_by        = string  // Slack user ID
approval_status    = 'approved'
post_status        = 'posted' | 'failed'
posted_at          = string  // ISO 8601
//   -> Update Notion row: ResponseStatus = 'posted'
//   -> Manager clicks Reject:
approval_status    = 'rejected'
//   -> Update Notion row: ResponseStatus = 'manual_required'
//   -> Send Slack thread: prompt manager to post manually

// ============================================================
// AGENT HANDOFF 3: Response Drafting Agent -> CRM and Reporting Agent
// Triggered only when post_status == 'posted'
// Fields passed: notion_row_id, reviewer_name, reviewer_email,
//                platform, star_rating, sentiment,
//                post_status, posted_at, approved_by
// ============================================================

// CRM AND REPORTING AGENT processing (per-review):
// Step 1: Search HubSpot by reviewer_email (primary)
//         Fallback: search by firstname + lastname (>=90% match required)
hubspot_contact_id  = string  // Matched ID or 'partial_record_created'

// Step 2: Create HubSpot timeline activity (Engagements API v1)
hubspot_activity_id = string
// Activity fields: platform, star_rating, sentiment,
//                  topic_summary, posted_at, notion_row link

// Step 3: Update Notion row
// ResponseStatus = 'posted'
notion_row_updated  = boolean

// ============================================================
// WEEKLY SCHEDULE TRIGGER: Every Monday 08:00 local time
// -> CRM and Reporting Agent (reporting function)
// ============================================================

// Query Notion tracker: CreatedAt >= report_week_start
//                        AND CreatedAt <= report_week_end
report_summary = {
  total_reviews:         integer,
  avg_rating:            float,
  response_rate_pct:     float,
  sentiment_breakdown:   { positive: int, neutral: int, negative: int },
  top_complaint_themes:  string[]   // Max 3 items from topic_summary
}

// Post Slack Block Kit report to #marketing channel
slack_report_ts = string  // Slack message timestamp

// ============================================================
// END OF FLOW
// ============================================================