Integration and API Spec

Integration and API Spec

Sales Pipeline Management

Primary data source and action target for deal records, pipeline stages, owner assignment, task creation, and close logging. Used by all three agents. The automation reads and writes to the Deals, Contacts, and Tasks objects via the HubSpot CRM API v3.

// Inbound webhook payload (deal.creation example)
{
  "subscriptionType": "deal.creation",
  "objectId": 12345678,
  "propertyName": "dealstage",
  "propertyValue": "appointmentscheduled",
  "changeSource": "CRM_UI",
  "occurredAt": 1713600000000
}

// Read deal record: GET /crm/v3/objects/deals/{dealId}?properties=dealname,amount,closedate,hubspot_owner_id,dealstage,hs_lastmodifieddate
// Update deal:    PATCH /crm/v3/objects/deals/{dealId}  { properties: { hubspot_owner_id, dealstage } }
// Create task:    POST /crm/v3/objects/tasks  { properties: { hs_task_subject, hs_task_status, hs_task_type, hubspot_owner_id }, associations: [{ dealId }] }

Used by the Pipeline Admin Agent to send stage-triggered emails on behalf of the assigned sales rep. The automation uses the Gmail API with send-on-behalf-of (delegated access), so emails appear to originate from the rep's address, not a generic inbox.

// POST https://gmail.googleapis.com/gmail/v1/users/{repEmail}/messages/send
// Authorization: Bearer {GMAIL_REFRESH_TOKEN_{REP_ID}} (exchanged for access token at runtime)

// Request body (RFC 2822 base64url-encoded)
From: {rep_full_name} <{rep_email}>
To: {prospect_email}
Subject: {template_subject_line}
Content-Type: text/html; charset=utf-8

// Merge fields resolved before encoding:
{{prospect_first_name}} -> HubSpot contact: firstname
{{deal_name}}           -> HubSpot deal:    dealname
{{rep_full_name}}       -> HubSpot owner:   firstName + lastName
{{rep_email}}           -> HubSpot owner:   email
{{company_name}}        -> HubSpot contact: company

Used by the Deal Health Monitor to deliver stall alerts to the deal owner and their manager. The Slack app posts to a configured channel or sends a direct message, depending on the alert configuration. All message content is dynamically populated from HubSpot deal data.

// POST https://slack.com/api/chat.postMessage
// Authorization: Bearer {SLACK_BOT_TOKEN}

// Request body:
{
  "channel": "{rep_slack_user_id or SLACK_CHANNEL_PIPELINE_ALERTS}",
  "text": "Deal stall alert: {deal_name}",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "*:warning: Stalled Deal Alert*\n*Deal:* {deal_name}\n*Days inactive:* {days_since_last_activity}\n*Stage:* {dealstage_label}\n*Owner:* {rep_full_name}" } },
    { "type": "actions", "elements": [
      { "type": "button", "text": { "type": "plain_text", "text": "View in HubSpot" },
        "url": "https://app.hubspot.com/contacts/{HUBSPOT_PORTAL_ID}/deal/{deal_id}" }
    ] }
  ]
}

Used by the Pipeline Reporting Agent to write daily pipeline summary rows and close-reason log entries. The Sheets API is used for targeted cell and row writes; the automation does not read from Sheets. Two sheets exist within a single Google Sheets document: one for the daily pipeline snapshot and one for the close-reason log.

// POST https://sheets.googleapis.com/v4/spreadsheets/{GSHEETS_PIPELINE_DOC_ID}/values/{GSHEETS_PIPELINE_SHEET_NAME}!A:I:append
// ?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS
// Authorization: Bearer {service_account_access_token}

// Request body:
{
  "values": [
    [ "{run_date}", "{deal_id}", "{deal_name}", "{dealstage_label}",
      "{amount}", "{days_in_stage}", "{hs_lastmodifieddate}",
      "{owner_full_name}", "{createdate}" ]
  ]
}

Used as a supplementary trigger source for the Pipeline Admin Agent. When a prospect books a meeting via Calendly, a webhook fires and the orchestration layer creates or updates the corresponding HubSpot deal record without waiting for a rep to log it manually.

// Inbound Calendly webhook payload (invitee.created)
{
  "event": "invitee.created",
  "payload": {
    "event_type": { "uri": "{CALENDLY_EVENT_TYPE_URI_SLUG}", "name": "Sales Discovery Call" },
    "invitee": {
      "name": "Jane Prospect",
      "email": "jane@prospect.com",
      "scheduled_event": { "start_time": "2024-05-10T14:00:00Z" }
    }
  }
}

// Resolved output to Pipeline Admin Agent:
prospect_email   -> invitee.email
prospect_name    -> invitee.name
meeting_datetime -> payload.invitee.scheduled_event.start_time
initial_stage    -> CALENDLY_STAGE_MAP[event_type_slug]

// CREDENTIAL STORE CONTENTS
// All values are encrypted at rest. Reference by key name only in workflow steps.

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN       = "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
HUBSPOT_WEBHOOK_SECRET          = "<32-char hex secret from HubSpot private app>"
HUBSPOT_PORTAL_ID               = "<your HubSpot portal numeric ID>"
HUBSPOT_PIPELINE_ID             = "<pipeline UUID from HubSpot pipelines API>"
HUBSPOT_STAGE_APPOINTMENT_SCHED = "<stage internal ID>"
HUBSPOT_STAGE_QUALIFIED         = "<stage internal ID>"
HUBSPOT_STAGE_PROPOSAL_SENT     = "<stage internal ID>"
HUBSPOT_STAGE_NEGOTIATION       = "<stage internal ID>"
HUBSPOT_STAGE_CLOSED_WON        = "<stage internal ID>"
HUBSPOT_STAGE_CLOSED_LOST       = "<stage internal ID>"
HUBSPOT_OWNER_MAP               = '{ "territory_rule_1": "owner_id_1", "territory_rule_2": "owner_id_2" }'

// Gmail (one entry per sales rep)
GMAIL_REFRESH_TOKEN_REP_001     = "<OAuth 2.0 refresh token for rep 1>"
GMAIL_REFRESH_TOKEN_REP_002     = "<OAuth 2.0 refresh token for rep 2>"
GMAIL_OAUTH_CLIENT_ID           = "<Google Cloud OAuth client ID>"
GMAIL_OAUTH_CLIENT_SECRET       = "<Google Cloud OAuth client secret>"
GMAIL_TEMPLATE_APPOINTMENT_SCHED = "<template string or template store key>"
GMAIL_TEMPLATE_PROPOSAL_SENT     = "<template string or template store key>"
GMAIL_TEMPLATE_NEGOTIATION       = "<template string or template store key>"

// Slack
SLACK_BOT_TOKEN                 = "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx"
SLACK_CHANNEL_PIPELINE_ALERTS   = "C0XXXXXXXXX"
SLACK_CHANNEL_OPS               = "C0YYYYYYYYY"
SLACK_INCOMING_WEBHOOK_URL      = "https://hooks.slack.com/services/T00/B00/XXXXXXXX"

// Google Sheets
GOOGLE_SERVICE_ACCOUNT_KEY      = '{ "type": "service_account", "project_id": "...", ... }'
GSHEETS_PIPELINE_DOC_ID         = "<Google Sheets document ID from URL>"
GSHEETS_PIPELINE_SHEET_NAME     = "Pipeline Snapshot"
GSHEETS_CLOSELOG_SHEET_NAME     = "Close Reason Log"

// Calendly
CALENDLY_ACCESS_TOKEN           = "<Calendly personal access token>"
CALENDLY_WEBHOOK_SIGNING_KEY    = "<Calendly webhook signing key>"
CALENDLY_ORG_URI                = "https://api.calendly.com/organizations/<uuid>"
CALENDLY_EVENT_TYPE_URI_DISCOVERY = "https://api.calendly.com/event_types/<uuid>"
CALENDLY_STAGE_MAP              = '{ "discovery": "HUBSPOT_STAGE_APPOINTMENT_SCHED" }'

// Orchestration config
STALL_THRESHOLD_BUSINESS_DAYS   = "5"
MONITOR_RUN_TIME                = "08:00"
REPORT_RUN_TIME                 = "07:00"
PROCESS_TIMEZONE                = "America/New_York"