Integration and API Spec

Integration and API Spec

Review and Reputation Management

Used by the Review Classifier Agent (Agent 1) to poll for new reviews via the Business Profile API, and by the Response Drafting Agent (Agent 2) to post approved responses. Polling replaces a webhook because the API does not offer push notifications for new reviews.

// Poll response (simplified)
GET accounts/{accountId}/locations/{locationId}/reviews
  -> reviews[].reviewId          string
  -> reviews[].reviewer.displayName  string
  -> reviews[].starRating         enum: ONE|TWO|THREE|FOUR|FIVE
  -> reviews[].comment            string
  -> reviews[].updateTime         ISO 8601 timestamp
// Reply POST body
POST .../reviews/{reviewId}/reply
  -> {"comment": "<approved_response_text>"}

Secondary review source consumed by Agent 1. Trustpilot's Business API requires a paid Business plan for write access; read access for polling new reviews also requires API credentials issued via Trustpilot's developer portal.

// Poll response (simplified)
GET /v1/business-units/{businessUnitId}/reviews
  -> reviews[].id                 string
  -> reviews[].consumer.displayName  string
  -> reviews[].stars              integer (1-5)
  -> reviews[].text               string
  -> reviews[].createdAt          ISO 8601 timestamp
// Webhook payload (if enabled)
POST /webhook/trustpilot/new-review
  Headers: X-Trustpilot-Signature: <hmac_sha256>
  Body:    {event: 'review.created', review: {...}}

Central review tracker used by Agent 1 to log each incoming review and by Agent 3 to read aggregate data for the weekly report. A single Notion database serves as the audit log for all review records across platforms.

// Create page (new review record)
POST https://api.notion.com/v1/pages
  Body: {
    parent: {database_id: notion_database_id},
    properties: {
      review_id, platform, reviewer_name, star_rating,
      sentiment, confidence_score, topic_summary,
      response_draft, created_at
    }
  }
// Update page (post-response)
PATCH https://api.notion.com/v1/pages/{page_id}
  Body: {properties: {response_posted, response_posted_at, approved_by, hubspot_contact_id}}

Used by Agent 2 to send manager escalation alerts for negative reviews (2 stars or below), and by Agent 3 to post the weekly reputation summary to the marketing channel. Two distinct Slack channels are targeted.

// Escalation alert post
POST https://slack.com/api/chat.postMessage
  channel: slack_escalation_channel_id
  blocks: [Section(review_text), Section(draft_response), Actions(approve_btn, edit_btn)]
// Approval callback inbound
POST /webhook/slack/approval-action
  Headers: X-Slack-Signature: v0={hmac}, X-Slack-Request-Timestamp: {ts}
  Payload: {action_id: 'approve'|'edit', response_url, message_ts, channel_id}
// Weekly report post
POST https://slack.com/api/chat.postMessage
  channel: slack_report_channel_id
  blocks: [Header, Section(volume), Section(avg_rating), Section(response_rate), Section(themes)]

Used exclusively by Agent 3 (CRM and Reporting Agent) to search for a matching contact by name or email and log the review outcome as a timeline activity. Anonymous or unmatched reviewers result in a partial record or a skipped CRM step.

// Contact search
POST https://api.hubapi.com/crm/v3/objects/contacts/search
  {filterGroups: [{filters: [{propertyName:'email', operator:'EQ', value: reviewer_email}]}]}
  -> results[0].id  -> hubspot_contact_id
// Timeline event creation
POST https://api.hubapi.com/crm/v3/timeline/events
  {eventTemplateId: hubspot_event_type_id,
   objectId: hubspot_contact_id,
   tokens: {review_platform, star_rating, sentiment, review_text, response_posted, response_posted_at}}

Used by Agent 2 (Response Drafting Agent) to post responses to review platforms that accept email-based replies rather than direct API write access. Also used as the fallback posting method when the Google Business Profile API write call fails.

// Send message
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
  Authorization: Bearer gmail_access_token
  Body: {raw: base64url(<MIME message>)}
  MIME headers: To, From, Subject: 'Response to your review on {platform}', Content-Type: text/plain
  -> {id: message_id, threadId, labelIds}

// Credential store contents

// Google Business Profile
gbp_client_id              = '<oauth_client_id>'
gbp_client_secret          = '<oauth_client_secret>'
gbp_access_token           = '<current_access_token>'
gbp_refresh_token          = '<refresh_token>'
gbp_account_id             = '<accounts/{id}>'
gbp_location_id            = '<locations/{id}>'
gbp_last_poll_cursor       = '<ISO8601 timestamp, updated each poll>'

// Trustpilot
tp_client_id               = '<trustpilot_api_key>'
tp_client_secret           = '<trustpilot_api_secret>'
tp_access_token            = '<current_bearer_token>'
tp_refresh_token           = '<refresh_token>'
tp_business_unit_id        = '<business_unit_uuid>'
tp_last_poll_cursor        = '<ISO8601 timestamp, updated each poll>'
tp_webhook_secret          = '<hmac_signing_secret>'  // if webhook enabled

// Notion
notion_api_token           = '<secret_xxxx>'
notion_database_id         = '<database_uuid>'

// Slack
slack_bot_token            = '<xoxb-xxxx>'
slack_signing_secret       = '<signing_secret>'
slack_escalation_channel_id = '<C0XXXXXXXXX>'
slack_report_channel_id    = '<C0YYYYYYYYY>'

// HubSpot
hubspot_private_app_token  = '<pat-na1-xxxx>'
hubspot_portal_id          = '<portal_integer_id>'
hubspot_event_type_id      = '<timeline_event_template_id>'

// Gmail
gmail_client_id            = '<oauth_client_id>'
gmail_client_secret        = '<oauth_client_secret>'
gmail_access_token         = '<current_access_token>'
gmail_refresh_token        = '<refresh_token>'
gmail_sender_address       = '<replies@yourdomain.com>'

// Agent configuration
brand_voice_guidelines     = '<plaintext brand voice doc, max 4000 chars>'
negative_review_threshold  = 2  // star_rating <= this value triggers escalation
approval_timeout_minutes   = 60