Integration and API Spec

Integration and API Spec

Churn Risk Identification

Used by Agent 1 (Churn Signal Aggregator) to pull per-account product usage metrics on a daily schedule. Queried via the Mixpanel Query API (JQL or Insights endpoint) to retrieve login frequency, active event counts, and last-seen timestamps for all active accounts.

// Query input
project_id: MIXPANEL_PROJECT_ID
date_from: today() - 14d
date_to: today() - 1d
filter: account_id IN [active_account_ids]
// Output fields returned per account
account_id, last_login_date, login_count_14d, key_event_count_14d, days_since_last_event

Used by Agent 1 (Churn Signal Aggregator) to retrieve open support ticket data per account. The Conversations API is queried to count open conversations, identify tickets older than 5 days, and count tickets opened in the past 14 days.

// Request
GET /conversations?state=open&updated_after={14_days_ago}&per_page=150
Authorization: Bearer INTERCOM_ACCESS_TOKEN
// Output fields extracted per conversation
conversation_id, company_id, created_at, updated_at, state,
ticket_age_days (derived: today - created_at), open_ticket_count (aggregated by company_id)

Used by both agents. Agent 1 reads account health notes and contact/company records. Agent 2 writes risk tier, triggering signals, and assigned owner back to company records, logs sent email activity, and creates follow-up tasks.

// Agent 1 read (company record)
GET /crm/v3/objects/companies/{id}?properties=name,hs_lastcontacteddate,
  hubspot_owner_id,churn_risk_tier,health_score_notes
// Agent 2 write (batch update risk tier)
PATCH /crm/v3/objects/companies/batch/update
  { inputs: [{ id, properties: { churn_risk_tier, churn_signals, last_risk_review_date } }] }
// Agent 2 create task
POST /crm/v3/objects/tasks
  { properties: { hs_task_subject, hs_task_body, hs_task_due_date, hubspot_owner_id } }
// Agent 2 log email activity (note)
POST /crm/v3/objects/notes
  { properties: { hs_note_body, hs_timestamp }, associations: [{ company_id }] }

Used by Agent 2 (Risk Scoring and Routing Agent) to post structured high-risk account alerts to a designated channel. Each alert includes account name, risk tier, triggering signals, and the assigned CSM.

// chat.postMessage payload
POST https://slack.com/api/chat.postMessage
Authorization: Bearer SLACK_BOT_TOKEN
{
  channel: SLACK_CHURN_ALERT_CHANNEL_ID,
  blocks: [
    { type: 'header', text: { type: 'plain_text', text: ':warning: High-Risk Account: {account_name}' } },
    { type: 'section', fields: [
        { type: 'mrkdwn', text: '*Risk tier:* High' },
        { type: 'mrkdwn', text: '*Assigned CSM:* <@{csm_slack_user_id}>' },
        { type: 'mrkdwn', text: '*Signals:* {churn_signals_summary}' },
        { type: 'mrkdwn', text: '*Last contact:* {last_contacted_date}' }
    ]}
  ]
}

Used by Agent 2 (Risk Scoring and Routing Agent) to generate a pre-drafted outreach email and, after CSM approval, to send the personalised message to the at-risk customer. Authentication is via the Google Workspace account of the sending CSM or a shared mailbox.

// users.messages.send payload (simplified)
POST https://gmail.googleapis.com/gmail/v1/users/{from_address}/messages/send
Authorization: Bearer {access_token}
{
  raw: base64url(
    From: {GMAIL_FROM_ADDRESS}
    To: {customer_email}
    Subject: {email_subject}
    MIME-Version: 1.0
    Content-Type: multipart/alternative
    // HTML part: rendered template with placeholders substituted
    // Plain text part: stripped version of HTML body
  )
}

Used by both agents as the orchestration run log and audit trail. Each daily run appends a row recording the run timestamp, accounts processed, risk tiers assigned, alerts sent, and any errors encountered. This provides a human-readable audit trail without querying the automation platform logs directly.

// Append run log row
POST https://sheets.googleapis.com/v4/spreadsheets/{SPREADSHEET_ID}/values/{SHEETS_LOG_TAB_NAME}!A:M:append
  ?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS
  { values: [[run_date, accounts_processed, high_risk_count, medium_risk_count,
               low_risk_count, alerts_sent, emails_sent, errors, run_duration_seconds]] }

// Credential store contents
// All values are encrypted at rest in the orchestration platform credential store.
// Reference by variable name in workflow nodes; never hardcode values.

MIXPANEL_PROJECT_ID              = "<mixpanel_project_id>"
MIXPANEL_SERVICE_ACCOUNT_USERNAME = "<service_account_username>"
MIXPANEL_SERVICE_ACCOUNT_SECRET   = "<service_account_secret>"
MIXPANEL_EVENT_LOGIN              = "<confirmed_login_event_name>"
MIXPANEL_EVENT_KEY_ACTION         = "<confirmed_key_action_event_name>"

INTERCOM_ACCESS_TOKEN             = "<intercom_oauth_access_token>"
INTERCOM_WORKSPACE_ID             = "<intercom_workspace_id>"
INTERCOM_COMPANY_ID_FIELD         = "<company_attribute_name_for_account_id>"
TICKET_AGE_THRESHOLD_DAYS         = "5"

HUBSPOT_PRIVATE_APP_TOKEN         = "<hubspot_private_app_access_token>"
HUBSPOT_PORTAL_ID                 = "<hubspot_portal_id>"
HUBSPOT_RISK_TIER_PROPERTY        = "churn_risk_tier"
HUBSPOT_CHURN_SIGNALS_PROPERTY    = "churn_signals"
HUBSPOT_LAST_RISK_REVIEW_PROPERTY = "last_risk_review_date"

SLACK_BOT_TOKEN                   = "xoxb-<bot_token>"
SLACK_CHURN_ALERT_CHANNEL_ID      = "<channel_id>"
SLACK_SIGNING_SECRET              = "<slack_app_signing_secret>"
SLACK_CSM_USER_ID_MAP             = "{\"<hubspot_owner_id>\": \"<slack_user_id>\", ...}"

GMAIL_SERVICE_ACCOUNT_JSON        = "<base64_encoded_service_account_key_json>"
GMAIL_FROM_ADDRESS                = "<outreach_sending_address>"
GMAIL_OUTREACH_TEMPLATE_HIGH_RISK = "<html_template_string_or_template_id>"

GOOGLE_SHEETS_LOG_SPREADSHEET_ID  = "<spreadsheet_id>"
SHEETS_LOG_TAB_NAME               = "RunLog"
SHEETS_SNAPSHOT_TAB_NAME          = "AccountSnapshot"

// Scoring thresholds (configurable; adjust after first 30-day review)
SCORE_LOGIN_DROP_THRESHOLD_DAYS   = "10"
SCORE_OPEN_TICKET_HIGH            = "3"
SCORE_TICKET_AGE_HIGH_DAYS        = "5"
SCORE_DAYS_NO_CONTACT_HIGH        = "30"
SCORE_HIGH_RISK_TOTAL_THRESHOLD   = "70"
SCORE_MEDIUM_RISK_TOTAL_THRESHOLD = "40"