Integration and API Spec

Integration and API Spec

Post-Meeting Recap and Follow-up

Provides meeting metadata (start time, end time, attendees, event title) used to detect qualifying sales meetings and populate the attendee list for the Gmail draft. The automation polls the Calendar API on a short interval or responds to a push notification channel registered via the watch endpoint.

// Output to Agent 1
calendar_event_id: string
event_title: string
end_time: ISO8601 datetime
attendees: [{ email: string, display_name: string }]
organizer_email: string

Provides a webhook signal when a meeting recording becomes available, supplementing the Google Calendar end-time trigger. The Meeting Trigger Agent uses this to confirm the call has fully ended and a recording exists before fetching the Fireflies.ai transcript.

// Webhook payload fields consumed by Agent 1
payload.object.id: string           // Zoom meeting ID
payload.object.topic: string         // meeting title for keyword filter
payload.object.start_time: ISO8601
payload.object.duration: integer     // minutes
payload.object.host_email: string
payload.object.recording_files[].download_url: string

The primary source of meeting transcripts and AI-generated summaries. The Meeting Trigger Agent queries the Fireflies.ai GraphQL API to retrieve the transcript matched to the meeting, and passes the full transcript text and summary to the Recap Drafting Agent.

// GraphQL query: GET transcript by meeting ID
query {
  transcript(id: "<meetingId>") {
    id
    title
    date
    duration
    organizer_email
    participants
    summary { overview action_items keywords }
    sentences { index speaker_name text raw_words }
  }
}

Receives the AI-generated recap email draft and saves it to the rep's Gmail Drafts folder, addressed to all meeting attendees. The Recap Drafting Agent also uses Gmail (via a Slack nudge) to prompt the rep to review the draft.

// Draft creation request body (Gmail API)
message.raw: base64url-encoded RFC 2822 message
// Headers included in raw message
To: <attendee_emails_joined_by_comma>
Subject: Recap: <event_title> - <event_date>
Content-Type: text/plain; charset=UTF-8

Receives a structured meeting summary block from the Recap Drafting Agent and appends it to the deal's designated Notion page. Acts as the team knowledge base record for the meeting.

// Block appended to deal Notion page
{
  type: 'toggle',
  toggle: {
    rich_text: [{ text: { content: '<event_title> | <event_date>' } }],
    children: [
      { type: 'paragraph', paragraph: { rich_text: [{ text: { content: 'Attendees: <attendee_names>' } }] } },
      { type: 'paragraph', paragraph: { rich_text: [{ text: { content: 'Summary: <ai_summary_overview>' } }] } },
      { type: 'paragraph', paragraph: { rich_text: [{ text: { content: 'Action Items: <action_items_list>' } }] } }
    ]
  }
}

The CRM and Task Sync Agent writes meeting outcomes to the correct deal record, creates follow-up tasks from extracted action items, and optionally advances the deal stage when a stage keyword is detected in the transcript.

// Deal update PATCH body
properties: {
  hs_meeting_body: '<ai_summary_overview>',
  notes_last_updated: '<ISO8601_timestamp>',
  dealstage: '<mapped_stage_id_or_unchanged>'
}
// Task creation POST body
properties: {
  hs_task_subject: '<action_item_text>',
  hs_task_status: 'NOT_STARTED',
  hs_timestamp: '<due_date_ISO8601>',
  hubspot_owner_id: '<rep_owner_id>'
}
associations: [{ to: { id: '<dealId>' }, types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 216 }] }]

Used by two agents for two distinct purposes: the Recap Drafting Agent sends a nudge to the rep when the Gmail draft is ready, and the CRM and Task Sync Agent posts a formatted deal-update message to the sales channel for deals above the configured value threshold.

// Rep nudge DM payload
{
  channel: '<rep_slack_user_id>',
  text: 'Your recap draft for <event_title> is ready in Gmail. Review and send when ready.',
  blocks: [ ... Block Kit blocks with link to Gmail drafts ... ]
}
// Deal update channel post payload
{
  channel: SLACK_SALES_CHANNEL_ID,
  text: 'Deal update: <deal_name> | <outcome_summary>',
  blocks: [ ... Block Kit blocks with HubSpot deal link ... ]
}

// Credential store contents (all entries required before first run)

// Google Calendar
GCAL_CALENDAR_ID                  // target calendar ID (e.g. rep@yourcompany.com)
GCAL_CLIENT_ID                    // OAuth 2.0 client ID from Google Cloud Console
GCAL_CLIENT_SECRET                // OAuth 2.0 client secret
GCAL_REFRESH_TOKEN                // per-rep refresh token (replicate per rep as GCAL_REFRESH_TOKEN_{REP_ID})
GCAL_INTERNAL_DOMAINS             // comma-separated list of internal email domains to filter out

// Zoom
ZOOM_CLIENT_ID                    // server-to-server OAuth app client ID
ZOOM_CLIENT_SECRET                // server-to-server OAuth app client secret
ZOOM_ACCOUNT_ID                   // Zoom account ID for token endpoint
ZOOM_WEBHOOK_SECRET_TOKEN         // secret token for HMAC webhook validation
ZOOM_MEETING_FILTER_KEYWORDS      // comma-separated keywords: 'sales,discovery,demo,prospect'

// Fireflies.ai
FIREFLIES_API_KEY                 // Bearer token from Fireflies.ai dashboard
FIREFLIES_FALLBACK_ENABLED        // boolean: 'true' enables calendar-only summary fallback

// Gmail
GMAIL_CLIENT_ID                   // OAuth 2.0 client ID
GMAIL_CLIENT_SECRET               // OAuth 2.0 client secret
GMAIL_REFRESH_TOKEN_{REP_ID}      // per-rep refresh token keyed by rep email slug
GMAIL_RECAP_TEMPLATE_ID           // plain-text template string for recap email structure

// Notion
NOTION_INTEGRATION_TOKEN          // internal integration secret from Notion dashboard
NOTION_DEALS_DATABASE_ID          // ID of the Notion Deals database
NOTION_SUMMARY_BLOCK_TEMPLATE     // JSON block template for meeting summary toggle block

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN         // private app token from HubSpot settings
HUBSPOT_PIPELINE_ID               // ID of the active sales pipeline
HUBSPOT_DEAL_STAGE_MAP            // JSON: { 'keyword': 'stage_id', ... }
HUBSPOT_MEETING_OUTCOME_FIELD     // internal property name e.g. 'hs_meeting_body'
HUBSPOT_STAGE_KEYWORD_CONFIDENCE  // float threshold for stage advancement e.g. 0.85

// Slack
SLACK_BOT_TOKEN                   // xoxb- prefixed bot OAuth token
SLACK_SALES_CHANNEL_ID            // channel ID (not name) for deal update posts
SLACK_DEAL_VALUE_THRESHOLD        // integer dollar amount e.g. 10000
SLACK_NUDGE_MESSAGE_TEMPLATE      // plain-text or Block Kit JSON for rep DM nudge
SLACK_DEAL_UPDATE_TEMPLATE        // plain-text or Block Kit JSON for sales channel post
SLACK_DEFAULT_REP_DM_CHANNEL      // fallback channel if users.lookupByEmail fails