Integration and API Spec

Integration and API Spec

Support Ticket Triage & Routing

Primary helpdesk platform. Tickets are ingested via webhook on creation or update, and categorization, priority tags, and assignment are written back via REST API.

// Inbound Webhook Payload (on ticket creation)
{
  ticket_id: 12345,
  requester_email: 'customer@example.com',
  subject: 'Payment not processing',
  description: 'I tried to upgrade my account but my card was declined...',
  created_at: '2024-03-14T09:30:00Z',
  status: 'new',
  custom_fields: { ... }
}
// Outbound API Call (write tags and assignment)
PUT /api/v2/tickets/12345
{
  custom_fields: [
    { id: 123456, value: 'billing' },
    { id: 123457, value: 'high' },
    { id: 123458, value: 'billing_queue' },
    { id: 123459, value: '2024-03-14T11:30:00Z' }
  ],
  assignee_id: 789456,
  status: 'open'
}

Real-time team notification of new ticket assignment. A single Incoming Webhook URL posts formatted messages to a designated support channel or user direct message.

// Incoming Webhook POST (send notification)
POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX
{
  blocks: [
    {
      type: 'section',
      text: { type: 'mrkdwn', text: '🆕 *New High-Priority Ticket*\nBilling Issue - Payment Failed' }
    },
    {
      type: 'context',
      elements: [
        { type: 'mrkdwn', text: 'Customer: alice@customer.com | SLA: 1 hour' }
      ]
    },
    {
      type: 'actions',
      elements: [
        {
          type: 'button',
          text: { type: 'plain_text', text: 'Open in Zendesk' },
          url: 'https://yourcompany.zendesk.com/agent/tickets/12345'
        }
      ]
    }
  ]
}

CRM logging and customer context. Triage decision (category, priority, assigned queue) is logged to the contact record for reporting and future reference.

// Lookup Contact by Email
GET /crm/v3/objects/contacts?limit=1&after=0&properties=email&filterGroups=[{filters:[{propertyName:'email',operator:'EQ',value:'customer@example.com'}]}]
// Response
{
  results: [
    {
      id: '456789',
      properties: { email: 'customer@example.com', firstname: 'Alice', lastname: 'Smith' }
    }
  ]
}
// Update Contact with Triage Data
PATCH /crm/v3/objects/contacts/456789
{
  properties: {
    last_ticket_category: 'billing',
    last_ticket_priority: 'high',
    last_assigned_support_queue: 'billing_queue',
    ticket_triage_count: 3
  }
}

Email ticket ingestion. Support tickets arriving via email are forwarded to a shared mailbox or label, then parsed by the automation. Subject and body are extracted and sent to the Ticket Analyzer.

// Watch Request (push notification setup)
POST /gmail/v1/users/support@yourcompany.com/watch
{
  topicName: 'projects/yourproject/topics/gmail-support',
  labelIds: ['Label_1']  // 'support/new-tickets' label ID
}
// Get Message (on push event)
GET /gmail/v1/users/support@yourcompany.com/messages/15e8d5f3e9b1a2c4?format=full
// Response (excerpt)
{
  id: '15e8d5f3e9b1a2c4',
  payload: {
    headers: [
      { name: 'From', value: 'customer@example.com' },
      { name: 'Subject', value: 'Urgent: Payment not processing' },
      { name: 'Date', value: 'Thu, 14 Mar 2024 09:30:00 +0000' }
    ],
    parts: [
      {
        mimeType: 'text/plain',
        body: { data: 'Base64-encoded message body...' }
      }
    ]
  }
}

// Zendesk Integration
ZENDESK_SUBDOMAIN: 'yourcompany'  // Used to construct API base URL
ZENDESK_API_TOKEN: '****REDACTED****'  // OAuth token or API token; rotated 90 days
ZENDESK_OAUTH_REFRESH_TOKEN: '****REDACTED****'  // If using OAuth; refresh before expiry

// Slack Integration
SLACK_WEBHOOK_SUPPORT_BILLING: 'https://hooks.slack.com/services/T00/B00/XXXX'  // #support-billing channel
SLACK_WEBHOOK_SUPPORT_TECHNICAL: 'https://hooks.slack.com/services/T00/B01/XXXX'  // #support-technical channel
SLACK_WEBHOOK_SUPPORT_ESCALATION: 'https://hooks.slack.com/services/T00/B02/XXXX'  // #support-escalation channel
SLACK_BOT_TOKEN: 'xoxb-****'  // Optional: for slack.users.lookupByEmail API calls

// HubSpot Integration
HUBSPOT_PRIVATE_APP_TOKEN: '****REDACTED****'  // Scopes: crm.objects.contacts.read, crm.objects.contacts.write
HUBSPOT_ACCOUNT_ID: '123456789'  // Used in all API calls

// Gmail Integration
GMAIL_SERVICE_ACCOUNT_JSON: '****REDACTED****'  // Full service account key (encrypted)
GMAIL_DELEGATED_EMAIL: 'support@yourcompany.com'  // Mailbox to monitor
GMAIL_LABEL_ID: 'Label_1'  // ID of 'support/new-tickets' label

// Workflow Automation Platform (Internal)
WORKFLOW_API_KEY: '****REDACTED****'  // For logging, state queries, credential refresh
WORKFLOW_ENVIRONMENT: 'production'  // Enum: staging, production
WORKFLOW_TIMEOUT_SECONDS: 300  // Max execution time per ticket
WORKFLOW_MAX_RETRIES: 3  // Retry failed API calls up to 3 times
WORKFLOW_RETRY_BACKOFF_MS: [1000, 2000, 4000]  // Exponential backoff schedule