Integration and API Spec

Integration and API Spec

Event and Webinar Promotion Automation

Used as the event brief source of truth and as the metrics write-back destination. The automation platform polls the designated event sheet for new rows where the Status column equals 'Confirmed'. It also writes registration count, attendance count, and email engagement figures back to the same row after the event completes.

// Trigger read
GET /v4/spreadsheets/{GSHEETS_SPREADSHEET_ID}/values/EventBriefInput
// Metrics write-back
PUT /v4/spreadsheets/{GSHEETS_SPREADSHEET_ID}/values/MetricsOutput!N{row}:R{row}
  body: { values: [[registrant_count, attendee_count, no_show_count, email_open_rate, processed_at]] }

Used by Agent 1 (Event Setup) to create the webinar registration and capture the registration URL, and by Agent 3 (Post-Event Sync) to retrieve the participant report after the event ends.

// Agent 1: Create webinar
POST https://api.zoom.us/v2/users/{ZOOM_WEBINAR_HOST_ID}/webinars
  body: { topic, start_time, duration, agenda, settings: { registration_type: 1, approval_type: 0 } }
// Response: extract join_url -> stored as event.zoom_registration_url
// Agent 3: Pull attendance report
GET https://api.zoom.us/v2/report/webinars/{webinarId}/participants
  query: { page_size: 300 }
// Response: participants[].status ('joined' | 'left') mapped to attendance_status

Used by Agent 1 to activate the pre-built email sequence for the confirmed event contact list, and by Agent 3 to create or update contact records with attendance tags and trigger segmented follow-up emails.

// Agent 1: Enrol contacts in sequence
POST https://api.hubapi.com/automation/v4/sequences/{HUBSPOT_SEQUENCE_ID}/enrollments
  body: { contactId, startAt: event_date_minus_14_days }
// Agent 3: Upsert contact
PATCH https://api.hubapi.com/crm/v3/objects/contacts/{contactId}
  body: { properties: { attendance_status, event_name, event_date, event_tags } }
// Agent 3: Send follow-up email (attendee)
POST https://api.hubapi.com/marketing/v3/transactional/single-email/send
  body: { emailId: HUBSPOT_ATTENDEE_FOLLOW_UP_EMAIL_ID, message: { to: contact_email } }
// Agent 3: Send follow-up email (no-show)
POST https://api.hubapi.com/marketing/v3/transactional/single-email/send
  body: { emailId: HUBSPOT_NOSHOW_FOLLOW_UP_EMAIL_ID, message: { to: contact_email } }

Used by Agent 2 (Social Promotion) to schedule three promotional posts to the company LinkedIn Page: an announcement post, a mid-cycle reminder post, and a day-of post. All posting is to a LinkedIn Page, not a personal profile. Post copy is AI-generated and must pass the human approval step before the scheduling API call is made.

// Schedule a LinkedIn Page post
POST https://api.linkedin.com/v2/ugcPosts
  headers: { Authorization: Bearer {LINKEDIN_ACCESS_TOKEN}, X-Restli-Protocol-Version: 2.0.0 }
  body: {
    author: 'urn:li:organization:{LINKEDIN_ORGANIZATION_ID}',
    lifecycleState: 'PUBLISHED',
    publishedAt: {unix_timestamp_ms},
    specificContent: { com.linkedin.ugc.ShareContent: {
      shareCommentary: { text: post_copy },
      shareMediaCategory: 'NONE'
    }},
    visibility: { com.linkedin.ugc.MemberNetworkVisibility: 'PUBLIC' }
  }

Used by Agent 2 to post a single internal launch notification to a designated Slack channel immediately after LinkedIn posts are scheduled. The message includes the event name, date, and Zoom registration URL.

// Post launch notification
POST https://slack.com/api/chat.postMessage
  headers: { Authorization: Bearer {SLACK_BOT_TOKEN} }
  body: {
    channel: '{SLACK_CHANNEL_ID}',
    text: 'EVENT LIVE: {event_name} on {event_date_formatted}. Registration: {zoom_registration_url}'
  }

// Credential store contents
// Google Sheets
GSHEETS_SERVICE_ACCOUNT_JSON      = { ...service_account_key_json... }
GSHEETS_SPREADSHEET_ID            = '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms'  // replace at setup

// Zoom
ZOOM_CLIENT_ID                    = 'xxxxxxxxxxxxxxxxxxxx'
ZOOM_CLIENT_SECRET                = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
ZOOM_ACCOUNT_ID                   = 'xxxxxxxxxxxx'
ZOOM_WEBINAR_HOST_ID              = 'xxxxxxxxxxxx'
ZOOM_WEBHOOK_SECRET_TOKEN         = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'  // reserved for future webhook

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN         = 'pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
HUBSPOT_SEQUENCE_ID               = '12345678'  // ID of pre-built announcement+reminder sequence
HUBSPOT_EVENT_LIST_ID             = '87654321'  // active list of target audience contacts
HUBSPOT_ATTENDEE_FOLLOW_UP_EMAIL_ID  = '11111111'  // published email template ID
HUBSPOT_NOSHOW_FOLLOW_UP_EMAIL_ID    = '22222222'  // published email template ID

// LinkedIn
LINKEDIN_CLIENT_ID                = 'xxxxxxxxxxxx'
LINKEDIN_CLIENT_SECRET            = 'xxxxxxxxxxxxxxxx'
LINKEDIN_ACCESS_TOKEN             = 'AQV...'  // refresh before 60-day expiry
LINKEDIN_REFRESH_TOKEN            = 'AQX...'  // refresh before 365-day expiry
LINKEDIN_ORGANIZATION_ID          = 'urn:li:organization:12345678'

// Slack
SLACK_BOT_TOKEN                   = 'xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
SLACK_CHANNEL_ID                  = 'C0XXXXXXXXX'  // internal events/marketing channel ID
SLACK_WEBHOOK_URL                 = 'https://hooks.slack.com/services/T.../B.../...'  // optional fallback

// Orchestration internals
APPROVAL_LINK_EXPIRY_HOURS        = 48
GSHEETS_POLL_INTERVAL_MINUTES     = 5
ZOOM_REPORT_DELAY_MINUTES         = 60  // offset after event end before Agent 3 runs