Integration and API Spec

Integration and API Spec

Sales Rep Activity Tracking

Gmail is polled by the Activity Capture Agent to detect outbound emails sent from a rep's account to an email address that exists as a HubSpot contact. The integration reads sent-mail metadata and body text; it does not write to Gmail.

// Input
GET /gmail/v1/users/me/messages?q=in:sent after:{last_poll_ts}
GET /gmail/v1/users/me/messages/{id}?format=full
// Output
{
  message_id: string,
  from_email: string,
  to_email: string[],
  subject: string,
  body_plain: string,
  sent_at_epoch: number
}

Google Calendar triggers the Activity Capture Agent when a calendar event ends and has at least one external attendee (i.e. an email domain different from the rep's workspace domain). It also supplies due-date context to the Follow-Up and Task Agent for next-step extraction.

// Input
GET /calendar/v3/calendars/primary/events
  ?timeMin={last_poll_iso}&timeMax={now_iso}&syncToken={token}
// Output
{
  event_id: string,
  summary: string,
  start_datetime: string (ISO 8601),
  end_datetime: string (ISO 8601),
  duration_minutes: number,
  attendees: [{ email: string, responseStatus: string }],
  description: string | null,
  conference_data: { entryPoints: [{ uri: string }] } | null
}

Zoom supplies cloud recording transcripts and meeting metadata to the Activity Capture Agent. The integration uses a Server-to-Server OAuth app registered in the Zoom Marketplace under the [YourCompany.com] account, which avoids per-user OAuth flows and allows access to all user recordings under the account.

// Inbound webhook payload (recording.completed)
{
  event: 'recording.completed',
  payload: {
    object: {
      uuid: string,
      host_email: string,
      topic: string,
      start_time: string (ISO 8601),
      duration: number (minutes),
      recording_files: [
        { file_type: 'TRANSCRIPT', download_url: string, status: 'completed' }
      ]
    }
  }
}
// Parsed transcript output
{
  meeting_uuid: string,
  host_email: string,
  topic: string,
  start_time: string,
  duration_minutes: number,
  transcript_text: string
}

HubSpot is the central data store for the automation. The Activity Capture Agent writes contact activity logs. The Follow-Up and Task Agent creates tasks. The Reporting and Nudge Agent queries activity records for the daily digest. All HubSpot access uses a single private app token with the scopes listed below.

// Contact lookup
POST /crm/v3/objects/contacts/search
  body: { filterGroups: [{ filters: [{ propertyName: 'email', operator: 'EQ', value: attendee_email }] }] }
// Activity (note) write
POST /crm/v3/objects/notes
  body: { properties: { hs_note_body, hs_timestamp }, associations: [contact_id, deal_id] }
// Task creation
POST /crm/v3/objects/tasks
  body: { properties: { hs_task_subject, hs_task_status:'NOT_STARTED', hs_timestamp, hs_task_priority:'MEDIUM', hubspot_owner_id }, associations: [contact_id, deal_id] }
// Activity query (Reporting Agent)
POST /crm/v3/objects/notes/search
  body: { filterGroups: [{ filters: [{ propertyName: 'hs_timestamp', operator: 'GTE', value: start_of_day_epoch_ms }] }] }

Google Sheets receives one appended row per logged activity from the Reporting and Nudge Agent each evening. The sheet acts as a live activity tracker for the sales manager and ops lead, removing the need for manual CRM exports.

// Append call
POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheet_id}/values/{range}:append
  ?valueInputOption=USER_ENTERED&insertDataOption=INSERT_ROWS
  body: { values: [[date, rep_name, rep_email, contact_name, contact_email,
                    activity_type, outcome, note_summary, deal_name, deal_stage, source]] }

Slack receives the formatted daily digest from the Reporting and Nudge Agent. Messages are posted to the configured sales channel each morning (8 AM) using a bot token. Stale-contact flag alerts and operational error alerts are posted to a separate ops channel.

// chat.postMessage payload
POST https://slack.com/api/chat.postMessage
  body: {
    channel: slack_sales_channel_id,
    blocks: [
      { type: 'header', text: { type: 'plain_text', text: 'Sales Activity Digest - {date}' } },
      { type: 'section', fields: [
          { type: 'mrkdwn', text: '*Rep*' },
          { type: 'mrkdwn', text: '*Activities Yesterday*' }
        ]
      },
      // one section block per rep
      { type: 'divider' },
      { type: 'section', text: { type: 'mrkdwn', text: ':warning: Stale contacts (>{threshold} days): {list}' } }
    ]
  }

// Gmail (one entry per rep, substitute {rep_id} for each)
gmail_oauth_{rep_id}                // OAuth 2.0 refresh token for rep Gmail account
gmail_rep_email_map                 // JSON: { rep_id: gmail_address }

// Google Calendar (one entry per rep)
gcal_oauth_{rep_id}                 // OAuth 2.0 refresh token for rep Calendar account
gcal_extra_calendars_{rep_id}       // JSON array of additional calendar IDs (may be [])
company_domain                      // string: e.g. 'yourcompany.com'

// Zoom
zoom_account_id                     // Zoom Server-to-Server account ID
zoom_client_id                      // Zoom app client ID
zoom_client_secret                  // Zoom app client secret
zoom_webhook_secret                 // HMAC secret for webhook signature validation
zoom_transcript_retention_days      // integer, default 30

// HubSpot
hubspot_private_app_token           // HubSpot private app Bearer token
hubspot_portal_id                   // HubSpot portal/account ID
hubspot_owner_email_map             // JSON: { rep_email: hubspot_owner_id }
hubspot_activity_type_map           // JSON: { 'EMAIL':'EMAIL','MEETING':'MEETING','CALL':'CALL' }
hubspot_pipeline_id                 // Active sales pipeline ID
hubspot_deal_stage_ids              // JSON: { stage_name: stage_id }
hubspot_stale_threshold_days        // integer, default 7

// Google Sheets
gsheets_service_account_json        // Full service account key JSON (stringified)
gsheets_spreadsheet_id              // Google Sheets file ID
gsheets_tab_name                    // string, default 'Daily Activity Log'
gsheets_named_range                 // string, default 'ActivityLog'

// Slack
slack_bot_token                     // Slack OAuth Bot token (xoxb-...)
slack_sales_channel_id              // Slack channel ID for daily digest
slack_ops_channel_id                // Slack channel ID for operational alerts
slack_digest_time                   // string HH:MM, default '08:00'
slack_stale_threshold_days          // integer, mirrors hubspot_stale_threshold_days

// Orchestration
cron_reporting_time                 // string HH:MM, default '18:00'
cron_digest_time                    // string HH:MM, default '08:00'
env                                 // string: 'sandbox' | 'production'