Integration and API Spec

Integration and API Spec

Customer Feedback Loop

Typeform is the primary survey intake channel. The automation listens for new responses via a registered webhook. The Typeform account must have at least one form configured to pass structured fields (customer name, email, feedback text, and optionally a rating field). The webhook payload is JSON and delivered to the orchestration layer endpoint per response submission.

// Inbound webhook payload (key fields)
event_id: string
form_id: string  // must match TYPEFORM_FORM_ID
token: string
answers[].field.ref: string  // mapped to respondent_email, respondent_name, feedback_text
answers[].text | .number | .email: string | number
submitted_at: ISO8601 timestamp
// Signature validation
Header: Typeform-Signature: sha256=<hmac>
Validate against TYPEFORM_WEBHOOK_SECRET before processing

Gmail serves two roles: as a trigger source (Agent 1 polls for feedback-tagged inbound emails) and as the send channel for customer acknowledgement emails (Agent 3). A dedicated Gmail label 'feedback-intake' is applied by a Gmail filter to qualifying inbound messages. The orchestration platform polls for messages with this label on a 2-minute interval.

// Agent 1 inbound (poll result per message)
message.id: string
message.threadId: string
message.payload.headers[From]: string  // extract respondent_email
message.payload.headers[Subject]: string
message.payload.body.data: base64url  // decode to get feedback_text
message.internalDate: epoch ms  // convert to ISO8601 for Sheets log
// Agent 3 outbound (send)
POST /gmail/v1/users/me/messages/send
body: { raw: base64url(MIME message) }
MIME To: respondent_email
MIME Subject: 'Thank you for your feedback'
MIME Body: template interpolated with customer_name, feedback_theme

Google Sheets is the central inter-agent data store. Agent 1 appends one row per feedback item. Agent 2 reads new rows (those with status column = 'pending') to begin sentiment processing. The sheet acts as the handoff boundary between Agent 1 and Agent 2. A single designated spreadsheet with a named tab 'feedback_log' is used.

// Agent 1 append (POST values:append)
range: 'feedback_log!A:J'
valueInputOption: 'RAW'
values: [[
  timestamp,         // col A: ISO8601
  source,            // col B: 'typeform' | 'gmail'
  respondent_email,  // col C
  respondent_name,   // col D
  feedback_text,     // col E
  '',                // col F: sentiment_score (blank, filled by Agent 2)
  '',                // col G: sentiment_label (blank, filled by Agent 2)
  '',                // col H: theme_tag (blank, filled by Agent 2)
  '',                // col I: hubspot_contact_id (blank, filled by Agent 2)
  'pending'          // col J: status
]]
// Agent 2 read
GET values/feedback_log  -> filter rows where col J = 'pending'
// Agent 2 update after processing
PATCH values/feedback_log!F{row}:J{row}
values: [[sentiment_score, sentiment_label, theme_tag, hubspot_contact_id, 'processed']]

HubSpot is used by Agent 2 to look up the respondent by email address and, if a match is found, add a note to the contact record and update a custom contact property tracking the latest feedback sentiment score. A Private App token is used rather than a full OAuth app to reduce scope surface area.

// Contact search
POST /crm/v3/objects/contacts/search
{ filterGroups: [{ filters: [{ propertyName: 'email', operator: 'EQ', value: respondent_email }] }] }
-> response.results[0].id  // hubspot_contact_id, or null if no match
// Property update
PATCH /crm/v3/objects/contacts/{hubspot_contact_id}
{ properties: { latest_feedback_score: sentiment_score } }
// Note creation
POST /crm/v3/objects/notes
{ properties: { hs_note_body: 'Feedback score: {sentiment_score} | Theme: {theme_tag} | Source: {source}', hs_timestamp: timestamp } }
-> response.id  // note_id
// Note-contact association
POST /crm/v3/associations/note/contact/batch/create
{ inputs: [{ from: { id: note_id }, to: { id: hubspot_contact_id }, type: 'NOTE_TO_CONTACT' }] }

Slack is used by Agent 2 to post a structured alert to a designated channel when a feedback record has a sentiment score of 4 or below. The alert includes the customer name, sentiment score, theme tag, and a direct link to the source response for the reviewer. A dedicated Slack Bot is used.

// Outbound message payload
POST https://slack.com/api/chat.postMessage
Authorization: Bearer {SLACK_BOT_TOKEN}
{
  channel: SLACK_ALERT_CHANNEL_ID,
  blocks: [
    { type: 'header', text: { type: 'plain_text', text: 'Urgent Feedback Alert' } },
    { type: 'section', fields: [
      { type: 'mrkdwn', text: '*Customer:* {respondent_name}' },
      { type: 'mrkdwn', text: '*Score:* {sentiment_score}/10' },
      { type: 'mrkdwn', text: '*Theme:* {theme_tag}' },
      { type: 'mrkdwn', text: '*Source:* {source}' }
    ]},
    { type: 'actions', elements: [
      { type: 'button', text: { text: 'View Response' }, url: response_url }
    ]}
  ]
}

Notion is used by Agent 3 to append each classified feedback entry to a running themes dashboard database. The database is pre-created in Notion with the required properties. The Notion Internal Integration is granted access to the specific database page only, not the entire workspace.

// Append new page to Notion database
POST https://api.notion.com/v1/pages
Notion-Version: 2022-06-28
Authorization: Bearer {NOTION_INTEGRATION_TOKEN}
{
  parent: { database_id: NOTION_DATABASE_ID },
  properties: {
    'Customer Name': { title: [{ text: { content: respondent_name } }] },
    'Date': { date: { start: timestamp } },
    'Source': { select: { name: source } },
    'Sentiment Score': { number: sentiment_score },
    'Sentiment Label': { select: { name: sentiment_label } },
    'Theme Tag': { select: { name: theme_tag } },
    'HubSpot Matched': { checkbox: hubspot_matched_bool }
  }
}

// Credential store contents (all values stored as encrypted secrets)

// Typeform
TYPEFORM_ACCESS_TOKEN         // OAuth 2.0 access token
TYPEFORM_REFRESH_TOKEN        // OAuth 2.0 refresh token
TYPEFORM_FORM_ID              // Target form ID (e.g. 'abc12345')
TYPEFORM_WEBHOOK_SECRET       // HMAC-SHA256 shared secret for signature validation

// Gmail
GMAIL_ACCESS_TOKEN            // OAuth 2.0 access token (Google)
GMAIL_REFRESH_TOKEN           // OAuth 2.0 refresh token (Google)
GMAIL_LABEL_ID                // Label ID for 'feedback-intake' (e.g. 'Label_1234567890')
GMAIL_SENDER_ADDRESS          // From address for outbound sends
GMAIL_TEMPLATE_POSITIVE_ID    // Template body or draft ID for positive sentiment
GMAIL_TEMPLATE_NEUTRAL_ID     // Template body or draft ID for neutral sentiment
GMAIL_TEMPLATE_NEGATIVE_ID    // Template body or draft ID for negative sentiment

// Google Sheets
SHEETS_ACCESS_TOKEN           // OAuth 2.0 access token (Google, may share with Gmail)
SHEETS_REFRESH_TOKEN          // OAuth 2.0 refresh token (Google, may share with Gmail)
SHEETS_SPREADSHEET_ID         // Target spreadsheet ID

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN     // Private App access token
HUBSPOT_FEEDBACK_SCORE_PROPERTY  // Internal name of custom contact property
HUBSPOT_ALERT_OWNER_ID        // HubSpot owner ID for escalated note assignment

// Slack
SLACK_BOT_TOKEN               // Bot User OAuth Token (xoxb-...)
SLACK_ALERT_CHANNEL_ID        // Channel ID (not name) for urgent alerts

// Notion
NOTION_INTEGRATION_TOKEN      // Internal Integration token
NOTION_DATABASE_ID            // Target database ID for themes dashboard

// Sentiment scoring (AI layer)
AI_MODEL_ENDPOINT             // Endpoint URL for sentiment scoring model
AI_MODEL_API_KEY              // API key for the sentiment scoring service
SENTIMENT_NEGATIVE_THRESHOLD  // Score threshold for Slack alert (default: 4)