Integration and API Spec

Integration and API Spec

Support Ticket Triage and Routing

Primary data source and write target. The workflow triggers on new ticket creation via Zendesk webhook. The automation reads ticket subject, body, requester email, and channel, then writes category tag, priority, assignee, and internal note back to the ticket record. All field writes use the Zendesk Tickets API v2.

// Inbound webhook payload (abbreviated)
{
  "ticket": {
    "id": 98231,
    "subject": "Cannot log into my account",
    "description": "I have been locked out since yesterday...",
    "requester": { "email": "customer@example.com" },
    "channel": "email",
    "created_at": "2024-05-13T09:14:22Z"
  }
}

// Write-back PATCH /api/v2/tickets/{id}.json
{
  "ticket": {
    "priority": "high",
    "assignee_id": 4420193,
    "custom_fields": [
      { "id": "{{ZENDESK_FIELD_ID_CATEGORY}}", "value": "account_access" },
      { "id": "{{ZENDESK_FIELD_ID_CONFIDENCE}}", "value": 0.91 }
    ],
    "comment": { "body": "[Auto-note] Category: account_access | Priority: high | Plan: Pro | Open tickets: 2", "public": false }
  }
}

CRM lookup used by the Ticket Classification Agent to enrich each ticket with customer plan tier, account status, and recent ticket count before classification runs. Read-only access required. No writes to HubSpot.

// GET /crm/v3/objects/contacts/search
{
  "filterGroups": [{
    "filters": [{
      "propertyName": "email",
      "operator": "EQ",
      "value": "customer@example.com"
    }]
  }],
  "properties": ["firstname", "lastname", "email", "{{HUBSPOT_PROP_PLAN_TIER}}", "{{HUBSPOT_PROP_ACCOUNT_STATUS}}", "hs_ticket_count"]
}

// Response (relevant fields extracted)
{
  "results": [{
    "id": "551839204",
    "properties": {
      "email": "customer@example.com",
      "plan_tier": "pro",
      "account_status": "active",
      "hs_ticket_count": "2"
    }
  }]
}

Used by the Routing and Notification Agent to send a direct message to the assigned support agent immediately after the ticket is assigned in Zendesk. The message includes ticket number, category, priority, and a direct deep-link to the ticket.

// POST https://slack.com/api/chat.postMessage
{
  "channel": "U04AGENTSLACKID",
  "text": "New ticket assigned to you",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Ticket #98231 assigned*\nCategory: account_access | Priority: high\nCustomer: customer@example.com (Pro plan)\n<https://{subdomain}.zendesk.com/agent/tickets/98231|Open ticket>"
      }
    }
  ]
}

Used by the Routing and Notification Agent to send a personalised acknowledgement email to the customer confirming ticket receipt, their ticket reference number, and an expected response window based on the assigned priority level.

// Gmail API message body (base64-encoded MIME, shown decoded)
From: Support <support@yourcompany.com>
To: customer@example.com
Reply-To: 98231@yoursubdomain.zendesk.com
Subject: We received your request [Ticket #98231]
Content-Type: text/plain

Hi {{customer_first_name}},

Thanks for reaching out. We have received your request and assigned it
ticket reference #98231. Based on the priority of your issue, you can
expect a response within {{priority_response_window}}.

Best regards,
The Support Team

Read-only runtime reference for the routing rules database. The Routing and Notification Agent queries a Notion database page to resolve ticket category and priority to the correct Zendesk agent ID. Notion stores the human-maintained routing table so routing rules can be updated by the team lead without a code change.

// POST /v1/databases/{{NOTION_ROUTING_RULES_DB_ID}}/query
{
  "filter": {
    "and": [
      { "property": "Category", "select": { "equals": "account_access" } },
      { "property": "Priority", "select": { "equals": "high" } }
    ]
  }
}

// Response (relevant fields)
{
  "results": [{
    "properties": {
      "Zendesk Agent ID": { "number": 4420193 },
      "Escalate to Human": { "checkbox": false }
    }
  }]
}

// Credential store: all keys required before production activation

// Zendesk
ZENDESK_API_TOKEN           = "<Zendesk API token for service account>"
ZENDESK_SUBDOMAIN           = "<yourcompany>"
ZENDESK_WEBHOOK_SECRET      = "<HMAC-SHA256 signing secret from Zendesk webhook settings>"
ZENDESK_FIELD_ID_CATEGORY   = "<numeric custom field ID for triage_category>"
ZENDESK_FIELD_ID_CONFIDENCE = "<numeric custom field ID for classification_confidence>"
ZENDESK_FALLBACK_AGENT_ID   = "<numeric Zendesk agent ID for manual review queue owner>"
AGENT_ROUTING_MAP           = "<JSON object: { zendesk_agent_id: name }>"

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN   = "<HubSpot Private App token>"
HUBSPOT_PROP_PLAN_TIER      = "<internal HubSpot property name for plan tier>"
HUBSPOT_PROP_ACCOUNT_STATUS = "<internal HubSpot property name for account status>"

// Slack
SLACK_BOT_TOKEN             = "<xoxb- Slack bot token>"
SLACK_WORKSPACE_ID          = "<T-prefixed Slack workspace ID>"
SLACK_FALLBACK_CHANNEL      = "<#channel-id for fallback and error alerts>"
AGENT_SLACK_MAP             = "<JSON object: { zendesk_agent_id: slack_user_id }>"

// Gmail
GMAIL_CLIENT_ID             = "<OAuth 2.0 client ID>"
GMAIL_CLIENT_SECRET         = "<OAuth 2.0 client secret>"
GMAIL_REFRESH_TOKEN         = "<OAuth 2.0 refresh token for support@ account>"
GMAIL_SENDER_ADDRESS        = "support@[YourCompany.com]"

// Notion
NOTION_INTEGRATION_TOKEN    = "<secret_xxx Notion internal integration token>"
NOTION_ROUTING_RULES_DB_ID  = "<32-character Notion database ID>"
NOTION_ACK_TEMPLATE_PAGE_ID = "<Notion page ID for acknowledgement email template>"

// Shared configuration
CLASSIFICATION_CONFIDENCE_THRESHOLD = 0.80
PRIORITY_RESPONSE_MAP       = "{ urgent: '2 hours', high: '4 hours', normal: '1 business day', low: '2 business days' }"