Integration and API Spec

Integration and API Spec

Proactive Customer Communication

HubSpot is the trigger source for the entire automation and the destination for all activity log write-backs. A private app token is the recommended auth method for server-to-server integration; OAuth 2.0 user-level tokens are acceptable but require refresh token handling. The automation listens for contact or deal property changes via webhook subscription.

// Inbound webhook payload (property change)
{ "objectId": "<contact_or_deal_id>", "objectType": "CONTACT" | "DEAL",
  "propertyName": "<trigger_property>", "propertyValue": "<new_value>",
  "changeTimestamp": 1716000000000 }

// Contact lookup response (GET /crm/v3/objects/contacts/{id})
{ "id": "<contact_id>", "properties": {
    "firstname": "Jane", "lastname": "Smith",
    "email": "jane@example.com", "phone": "+1...",
    "preferred_channel": "email" | "sms" | "chat",
    "notification_status": "<trigger_value>" } }

// Activity write-back (POST /crm/v3/timeline/events)
{ "eventTemplateId": "<HUBSPOT_TIMELINE_EVENT_TYPE_ID>",
  "objectId": "<contact_id>",
  "tokens": { "channel": "email", "sent_at": "ISO8601", "message_preview": "..." } }

Google Sheets holds the fallback and supplementary channel preference lookup table. It is read by Agent 1 (Status Monitor Agent) when the HubSpot contact record does not carry a populated preferred_channel property. Authentication uses a Google service account with the Sheets API enabled; no user-level OAuth flow is needed.

// Read request (GET spreadsheets/{id}/values/{range})
range: "Preferences!A:D"

// Response row
[ "<hubspot_contact_id>", "jane@example.com", "email" | "sms" | "chat", "FALSE" ]

// Fallback behaviour if contact not found in sheet
preferred_channel defaults to "email"

Slack serves two distinct functions: the supervisor approval interface used by Agent 2 (Message Drafting Agent) for sensitive drafts, and the hourly team digest channel used by Agent 3 (Delivery and Logging Agent). Both functions use the same Slack App bot token but post to different channels.

// Approval message payload (chat.postMessage)
{ "channel": "<SLACK_APPROVAL_CHANNEL_ID>",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
        "text": "*Sensitive draft for review*\nContact: Jane Smith\nStatus: Order delayed\nChannel: email" } },
    { "type": "actions", "elements": [
        { "type": "button", "text": { "type": "plain_text", "text": "Approve" },
          "action_id": "approve_draft", "value": "<draft_id>:<contact_id>", "style": "primary" },
        { "type": "button", "text": { "type": "plain_text", "text": "Edit and Approve" },
          "action_id": "edit_draft", "value": "<draft_id>:<contact_id>" } ] } ] }

// Interaction callback payload (from Slack to orchestration endpoint)
{ "type": "block_actions", "actions": [{ "action_id": "approve_draft",
  "value": "<draft_id>:<contact_id>" }],
  "user": { "id": "<supervisor_slack_id>" } }

Gmail is the primary email delivery channel used by Agent 3 (Delivery and Logging Agent). Messages are sent on behalf of a designated support mailbox using a delegated Google Workspace service account or a user-level OAuth token. Gmail is used when the customer's preferred_channel resolves to 'email' or when no preference is set.

// Send request (POST /gmail/v1/users/{userId}/messages/send)
{ "raw": "<base64url-encoded RFC 2822 message>" }

// Decoded message structure
From: Support <support@yourcompany.com>
To: jane@example.com
Subject: Your order update from [YourCompany.com]
MIME-Version: 1.0
Content-Type: multipart/alternative; boundary="boundary_string"
List-Unsubscribe: <mailto:unsubscribe@yourcompany.com?subject=unsubscribe>

// API response
{ "id": "<gmail_message_id>", "threadId": "<thread_id>", "labelIds": ["SENT"] }

Intercom is the in-app and chat delivery channel used by Agent 3 when the customer's preferred_channel resolves to 'chat'. Messages are sent as outbound conversations using the Intercom REST API. The integration targets an existing Intercom workspace and requires a valid user or contact record in Intercom for each recipient.

// Create outbound conversation (POST /conversations)
{ "from": { "type": "admin", "id": "<INTERCOM_SENDER_ADMIN_ID>" },
  "to": { "type": "user", "id": "<intercom_user_id>" },
  "subject": "Update from [YourCompany.com]",
  "body": "<message_body_html>" }

// API response
{ "type": "conversation", "id": "<conversation_id>",
  "created_at": 1716000000, "state": "open" }

Twilio is the SMS delivery channel used by Agent 3 when the customer's preferred_channel resolves to 'sms'. Messages are sent via the Twilio Messaging Service to ensure optimal sender selection and compliance. The integration uses Twilio's REST API with HTTP Basic Auth.

// Send SMS (POST /2010-04-01/Accounts/{AccountSid}/Messages.json)
Content-Type: application/x-www-form-urlencoded
MessagingServiceSid=<TWILIO_MESSAGING_SERVICE_SID>
&To=+1XXXXXXXXXX
&Body=Hi Jane, your order has shipped. Track it here: https://...
&StatusCallback=<TWILIO_STATUS_CALLBACK_URL>

// API response
{ "sid": "<message_sid>", "status": "queued",
  "to": "+1XXXXXXXXXX", "from": "<selected_sender>",
  "date_created": "...", "price": null }

// Status callback payload (delivered to orchestration endpoint)
{ "MessageSid": "<message_sid>", "MessageStatus": "delivered" | "failed" | "undelivered",
  "ErrorCode": null | "<code>", "To": "+1XXXXXXXXXX" }

// Credential store: variable names and descriptions

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN        // Private app token for all HubSpot API calls
HUBSPOT_PORTAL_ID                // HubSpot portal (account) ID
HUBSPOT_TRIGGER_PROPERTIES       // Comma-separated list of property names to watch
HUBSPOT_ELIGIBLE_STAGE_IDS       // JSON map of status_key to pipeline stage ID
HUBSPOT_TIMELINE_EVENT_TYPE_ID   // Timeline event template ID for activity log
HUBSPOT_CLIENT_SECRET            // Used for webhook signature validation

// Google Sheets
GSHEETS_SERVICE_ACCOUNT_JSON     // Full JSON key for service account (base64-encoded)
GSHEETS_PREFERENCE_SHEET_ID      // Spreadsheet ID
GSHEETS_PREFERENCE_TAB_NAME      // Sheet tab name (default: 'Preferences')
GSHEETS_COLUMN_MAP               // JSON map: { contact_id: 0, email: 1, preferred_channel: 2, opt_out: 3 }

// Slack
SLACK_BOT_TOKEN                  // OAuth bot token (xoxb-...)
SLACK_SIGNING_SECRET             // Used for interaction callback signature validation
SLACK_APPROVAL_CHANNEL_ID        // Channel ID for sensitive draft approval messages
SLACK_DIGEST_CHANNEL_ID          // Channel ID for hourly team digest
SLACK_SUPERVISOR_USER_ID         // Slack user ID or group ID for @mention in approvals
SLACK_APPROVAL_TIMEOUT_MINUTES   // Timeout before escalation (recommended: 60)

// Gmail
GMAIL_SERVICE_ACCOUNT_JSON       // Full JSON key for delegated service account (base64-encoded)
GMAIL_SENDER_ADDRESS             // From address (e.g. support@yourcompany.com)
GMAIL_SENDER_NAME                // Display name (e.g. '[YourCompany.com] Support')
GMAIL_REPLY_TO                   // Reply-to address if different from sender
GMAIL_TEMPLATE_IDS               // JSON map of status_key to template file path or ID

// Intercom
INTERCOM_ACCESS_TOKEN            // Bearer token for Intercom REST API
INTERCOM_WORKSPACE_ID            // Intercom workspace ID
INTERCOM_SENDER_ADMIN_ID         // Admin ID that appears as message sender

// Twilio
TWILIO_ACCOUNT_SID               // Twilio Account SID (sub-account preferred)
TWILIO_AUTH_TOKEN                // Twilio Auth Token (used for Basic Auth and callback validation)
TWILIO_MESSAGING_SERVICE_SID     // Messaging Service SID (use instead of From number)
TWILIO_STATUS_CALLBACK_URL       // Orchestration platform endpoint for delivery receipts