Integration and API Spec

Integration and API Spec

VIP Customer Management

Xero is the spend data source for the VIP Tier Agent. The integration reads invoice and payment records to calculate each contact's cumulative spend and compare it against tier thresholds defined in the credential store.

// Input
GET /api.xro/2.0/Invoices?where=Status=="AUTHORISED"OR Status=="PAID"&modifiedAfter={last_poll_ts}
// Key fields extracted
Invoice.Contact.ContactID  -> xero_contact_id
Invoice.SubTotal           -> invoice_subtotal
Invoice.CurrencyRate       -> currency_rate
Invoice.DateString         -> invoice_date
// Output to Agent 1
{ xero_contact_id, cumulative_spend_usd, last_invoice_date }

HubSpot is the central CRM used by all three agents: Agent 1 reads and writes contact tier properties, Agent 2 manages sequence enrolment and timeline events, and Agent 3 reads VIP flag status when a Zendesk ticket arrives.

// Input: contact lookup by xero_contact_id
GET /crm/v3/objects/contacts/search
  filter: hubspot_xero_contact_id == {xero_contact_id}
// Output: existing tier state
{ hs_object_id, vip_tier, vip_qualification_date, email, firstname, lastname, hubspot_owner_id }
// Input: tier update (PATCH)
PATCH /crm/v3/objects/contacts/{hs_object_id}
  body: { vip_tier, vip_qualification_date, vip_tier_changed }
// Input: sequence enrolment
POST /automation/v4/sequences/enrollments
  body: { sequenceId: HUBSPOT_SEQ_{TIER}, contactId: hs_object_id, senderEmail }

Gmail delivers personalised tier-up and check-in emails generated by the VIP Outreach Agent. All emails are sent from the authorised account manager mailbox associated with the contact owner.

// Input from Agent 2
{ recipient_email, first_name, tier_label, account_manager_name,
  benefit_summary, template_key, sender_refresh_token }
// Action
POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
  body: RFC 2822 MIME message encoded as base64url
// Output
{ messageId, threadId } -> logged to HubSpot timeline as engagement

Zendesk is monitored by the VIP Support Escalation Agent. When a new ticket arrives, the agent checks whether the submitter is a VIP-flagged HubSpot contact and applies a priority tag if so.

// Inbound webhook payload (selected fields)
{ ticket.id, ticket.subject, ticket.requester.email,
  ticket.requester.name, ticket.created_at, ticket.status }
// Lookup: is requester a VIP contact?
HubSpot contact search by email -> vip_tier != 'none'
// Action: apply tag
PUT /api/v2/tickets/{ticket.id}
  body: { ticket: { tags: [...existing_tags, ZENDESK_VIP_TAG],
                    priority: 'high' } }
// Output to Agent 3
{ ticket_id, ticket_url, requester_email, vip_tier, hubspot_contact_url }

Slack is the internal alert channel for the VIP Support Escalation Agent. It delivers real-time notifications to assigned account managers when a VIP ticket is created or a survey response falls below the alert threshold.

// Input from Agent 3 (ticket alert)
{ contact_first_name, vip_tier, ticket_id, ticket_url,
  hubspot_contact_url, account_manager_slack_user_id }
// Action
POST https://slack.com/api/chat.postMessage
  body: { channel: SLACK_CHANNEL_VIP_ESCALATIONS,
          blocks: [ ...SLACK_BLOCK_TICKET_ALERT rendered with above fields ] }
// Input from Agent 3 (survey alert)
{ contact_first_name, vip_tier, survey_score, typeform_response_url,
  hubspot_contact_url, account_manager_slack_user_id }
// Action
POST https://slack.com/api/chat.postMessage
  body: { channel: SLACK_CHANNEL_SURVEY_ALERTS,
          blocks: [ ...SLACK_BLOCK_SURVEY_ALERT rendered with above fields ] }

Typeform dispatches quarterly VIP satisfaction surveys triggered by Agent 2 at the 90-day mark of a contact's VIP enrolment. Survey response webhooks are consumed by Agent 3 to detect low scores and fire Slack alerts.

// Outbound: generate prefilled survey link (Agent 2)
GET /forms/{TYPEFORM_VIP_SURVEY_FORM_ID}
  -> construct prefilled URL with hidden fields:
     ?hubspot_contact_id={hs_object_id}&contact_email={email}&vip_tier={vip_tier}
// Log send event on HubSpot timeline
POST /crm/v3/timeline/events  body: { eventTemplateId, objectId, tokens }

// Inbound webhook payload (Agent 3)
{ form_response.token, form_response.submitted_at,
  form_response.hidden.hubspot_contact_id,
  form_response.hidden.vip_tier,
  form_response.answers[].field.ref == 'satisfaction_score' .number }
// Routing logic
if satisfaction_score < TYPEFORM_ALERT_SCORE_THRESHOLD -> fire Slack survey alert
else                                                    -> log response, no alert

// Xero
XERO_CLIENT_ID                  = <OAuth app client ID>
XERO_CLIENT_SECRET              = <OAuth app client secret>
XERO_TENANT_ID                  = <Xero organisation tenant UUID>
XERO_REFRESH_TOKEN              = <current refresh token, auto-rotated>
XERO_POLL_INTERVAL_MINUTES      = 15

// VIP tier thresholds (USD cumulative spend)
VIP_TIER_BRONZE_THRESHOLD       = <integer, e.g. 1000>
VIP_TIER_SILVER_THRESHOLD       = <integer, e.g. 5000>
VIP_TIER_GOLD_THRESHOLD         = <integer, e.g. 15000>

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN       = <bearer token>
HUBSPOT_WEBHOOK_SECRET          = <HMAC signing secret from HubSpot app>
HUBSPOT_APP_ID                  = <numeric app ID for timeline events>
HUBSPOT_PORTAL_ID               = <HubSpot portal/account ID>
HUBSPOT_SEQ_BRONZE              = <sequence ID integer>
HUBSPOT_SEQ_SILVER              = <sequence ID integer>
HUBSPOT_SEQ_GOLD                = <sequence ID integer>
HUBSPOT_OWNER_ID_RO             = <HubSpot owner ID for Rachel Oduya>
HUBSPOT_OWNER_ID_TF             = <HubSpot owner ID for Tom Fielding>
HUBSPOT_OWNER_ID_PS             = <HubSpot owner ID for Priya Shan>

// Gmail
GMAIL_CLIENT_ID                 = <Google OAuth client ID>
GMAIL_CLIENT_SECRET             = <Google OAuth client secret>
GMAIL_REFRESH_TOKEN_RO          = <refresh token for Rachel Oduya mailbox>
GMAIL_REFRESH_TOKEN_TF          = <refresh token for Tom Fielding mailbox>
GMAIL_FALLBACK_SENDER           = <fallback sender email address>
GMAIL_TEMPLATE_TIER_UP_BRONZE   = <Google Doc ID>
GMAIL_TEMPLATE_TIER_UP_SILVER   = <Google Doc ID>
GMAIL_TEMPLATE_TIER_UP_GOLD     = <Google Doc ID>
GMAIL_TEMPLATE_CHECKIN_30       = <Google Doc ID>
GMAIL_TEMPLATE_CHECKIN_60       = <Google Doc ID>
GMAIL_TEMPLATE_CHECKIN_90       = <Google Doc ID>

// Zendesk
ZENDESK_SUBDOMAIN               = <subdomain string, e.g. yourcompany>
ZENDESK_OAUTH_TOKEN             = <bearer token>
ZENDESK_WEBHOOK_SECRET          = <HMAC signing secret from Zendesk>
ZENDESK_TRIGGER_ID              = <numeric trigger ID>
ZENDESK_VIP_TAG                 = vip_priority

// Slack
SLACK_BOT_TOKEN                 = <xoxb- prefixed bot token>
SLACK_CHANNEL_VIP_ESCALATIONS   = <channel ID, e.g. C0XXXXXXX>
SLACK_CHANNEL_SURVEY_ALERTS     = <channel ID>
SLACK_USER_ID_RO                = <Slack user ID for Rachel Oduya>
SLACK_USER_ID_TF                = <Slack user ID for Tom Fielding>
SLACK_USER_ID_PS                = <Slack user ID for Priya Shan>
SLACK_BLOCK_TICKET_ALERT        = <Block Kit JSON template string>
SLACK_BLOCK_SURVEY_ALERT        = <Block Kit JSON template string>

// Typeform
TYPEFORM_ACCESS_TOKEN           = <personal access token>
TYPEFORM_CLIENT_ID              = <OAuth app client ID>
TYPEFORM_CLIENT_SECRET          = <OAuth app client secret>
TYPEFORM_WEBHOOK_SECRET         = <HMAC signing secret>
TYPEFORM_VIP_SURVEY_FORM_ID     = <form ID string>
TYPEFORM_WEBHOOK_ID             = <registered webhook ID>
TYPEFORM_ALERT_SCORE_THRESHOLD  = 6