Developer Handover Pack

Developer Handover Pack

Support Ticket Triage & Routing

Reads the subject line and full body of each new Zendesk ticket, cross-references the customer's CRM record fetched from HubSpot, and applies a trained classification schema to output a category label and a priority score. Handles ambiguous language and multi-issue tickets by selecting the dominant primary intent. Where confidence falls below the defined threshold, the agent flags the ticket for human review rather than writing a speculative classification. Output fields are written directly back to the ticket record in Zendesk before the Routing and Notification Agent fires.

// Input
zendesk.ticket.id          : string   // Zendesk ticket ID
zendesk.ticket.subject     : string   // Ticket subject line
zendesk.ticket.body        : string   // Full plain-text ticket body
zendesk.ticket.channel     : string   // email | chat | web_form
zendesk.requester.email    : string   // Customer email address
hubspot.contact.plan_tier  : string   // e.g. Free | Starter | Pro | Enterprise
hubspot.contact.account_status : string // active | churned | trial
hubspot.contact.open_tickets   : integer // Count of currently open tickets
hubspot.contact.recent_ticket_ids : array<string>

// Output
classification.category    : string   // billing | technical | account_access | general
classification.priority    : string   // low | normal | high | urgent
classification.confidence  : float    // 0.0 to 1.0
classification.primary_intent : string // One-sentence summary of dominant issue
classification.flag_for_review : boolean // true if confidence < 0.70

// On low confidence (flag_for_review = true)
zendesk.ticket.tag         : string   // 'triage_review_required'
zendesk.ticket.assignee    : string   // Team Lead queue (manual exception path)

Fires immediately after the Ticket Classification Agent has written category and priority to the Zendesk ticket record. Applies a routing rule table to match the ticket's category and priority combination to the correct agent or specialist queue, updates the Zendesk assignee field, adds a pre-formatted internal context note, sends a Slack direct message to the assigned agent, and dispatches a personalised acknowledgement email to the customer via Gmail. This agent handles all post-classification actions in sequence; if any downstream action fails, the failure is logged and a fallback Slack alert is sent to the Team Lead.

// Input
zendesk.ticket.id          : string
zendesk.ticket.subject     : string
zendesk.requester.email    : string
zendesk.requester.name     : string
classification.category    : string   // billing | technical | account_access | general
classification.priority    : string   // low | normal | high | urgent
classification.primary_intent : string
hubspot.contact.plan_tier  : string
hubspot.contact.open_tickets   : integer
routing_rules_table        : object   // Loaded from Notion or config store at runtime

// Output
zendesk.ticket.assignee_id : string   // Zendesk agent user ID
zendesk.internal_note      : string   // Formatted context note body
slack.dm.recipient         : string   // Slack user ID of assigned agent
slack.dm.message           : string   // Ticket number, category, priority, direct URL
gmail.to                   : string   // Customer email address
gmail.subject              : string   // 'We received your request [Ticket #XXXXX]'
gmail.body                 : string   // Personalised acknowledgement with SLA window

// On routing or notification failure
error_log.event            : string   // 'routing_failed' | 'slack_failed' | 'gmail_failed'
error_log.ticket_id        : string
error_log.timestamp        : datetime
slack.fallback_alert.channel : string // #support-ops or Team Lead DM

// ─────────────────────────────────────────────────────────────────
// TRIGGER: New ticket created in Zendesk (any inbound channel)
// ─────────────────────────────────────────────────────────────────
WEBHOOK_PAYLOAD {
  zendesk.ticket.id          : '98432'
  zendesk.ticket.subject     : 'Cannot access my account after password reset'
  zendesk.ticket.body        : '<full plain-text body>'
  zendesk.ticket.channel     : 'email'
  zendesk.ticket.created_at  : '2025-06-03T09:14:22Z'
  zendesk.requester.email    : 'customer@example.com'
  zendesk.requester.name     : 'Alex Rivera'
}

// ─────────────────────────────────────────────────────────────────
// STEP 1: HubSpot contact lookup (by requester email)
// ─────────────────────────────────────────────────────────────────
HubSpot.Contacts.search({
  filterGroups: [{ filters: [{ propertyName: 'email',
                              operator: 'EQ',
                              value: zendesk.requester.email }] }]
})
RETURNS {
  hubspot.contact.id             : 'hs-1029384'
  hubspot.contact.plan_tier      : 'Pro'
  hubspot.contact.account_status : 'active'
  hubspot.contact.open_tickets   : 1
  hubspot.contact.recent_ticket_ids : ['98100', '97881']
}
// If no HubSpot record: set hubspot.contact.plan_tier = 'unknown',
//   log 'hubspot_record_not_found', continue to classification.

// ─────────────────────────────────────────────────────────────────
// AGENT HANDOFF 1: Ticket Classification Agent receives merged payload
// ─────────────────────────────────────────────────────────────────
CLASSIFICATION_INPUT {
  ticket_id        : zendesk.ticket.id
  subject          : zendesk.ticket.subject
  body             : zendesk.ticket.body
  channel          : zendesk.ticket.channel
  requester_email  : zendesk.requester.email
  plan_tier        : hubspot.contact.plan_tier
  account_status   : hubspot.contact.account_status
  open_tickets     : hubspot.contact.open_tickets
}

// Classification model evaluates subject + body + account context
CLASSIFICATION_OUTPUT {
  classification.category       : 'account_access'
  classification.priority       : 'high'
  classification.confidence     : 0.91
  classification.primary_intent : 'Customer locked out after password reset'
  classification.flag_for_review: false
}

// ─────────────────────────────────────────────────────────────────
// CONFIDENCE GATE
// ─────────────────────────────────────────────────────────────────
IF classification.confidence < 0.70 THEN
  zendesk.PUT /tickets/98432 {
    tags: ['triage_review_required'],
    assignee_id: TEAM_LEAD_USER_ID
  }
  LOG 'low_confidence_routed_to_human' -> error_log table
  HALT  // Routing and Notification Agent does not fire
END IF

// ─────────────────────────────────────────────────────────────────
// STEP 2: Write classification fields back to Zendesk ticket
// ─────────────────────────────────────────────────────────────────
Zendesk.PUT /api/v2/tickets/98432 {
  priority : 'high'
  tags     : ['account_access']
  custom_fields: [
    { id: CATEGORY_FIELD_ID, value: 'account_access' },
    { id: CONFIDENCE_FIELD_ID, value: 0.91 }
  ]
}

// Dedupe check: if category field already populated, skip and log
// 'duplicate_webhook_skipped' then HALT

// ─────────────────────────────────────────────────────────────────
// AGENT HANDOFF 2: Routing and Notification Agent receives output
// ─────────────────────────────────────────────────────────────────
ROUTING_INPUT {
  ticket_id        : '98432'
  subject          : zendesk.ticket.subject
  requester_email  : 'customer@example.com'
  requester_name   : 'Alex Rivera'
  category         : 'account_access'
  priority         : 'high'
  primary_intent   : 'Customer locked out after password reset'
  plan_tier        : 'Pro'
  open_tickets     : 1
  routing_rules    : { account_access+high: AGENT_USER_ID_42 }
}

// ─────────────────────────────────────────────────────────────────
// STEP 3: Assign ticket in Zendesk
// ─────────────────────────────────────────────────────────────────
Zendesk.PUT /api/v2/tickets/98432 {
  assignee_id: 'AGENT_USER_ID_42'
}

// ─────────────────────────────────────────────────────────────────
// STEP 4: Add internal context note to ticket
// ─────────────────────────────────────────────────────────────────
Zendesk.POST /api/v2/tickets/98432/comments {
  body   : '[AUTO] Category: Account Access | Priority: High\n
             Plan Tier: Pro | Open tickets: 1\n
             Intent: Customer locked out after password reset\n
             Classified at: 2025-06-03T09:14:35Z'
  public : false
}

// ─────────────────────────────────────────────────────────────────
// STEP 5: Slack DM to assigned agent
// ─────────────────────────────────────────────────────────────────
Slack.POST /api/chat.postMessage {
  channel : 'SLACK_USER_ID_AGENT_42'
  text    : ':ticket: New ticket #98432 assigned to you\n
             Category: Account Access | Priority: High\n
             https://[YourCompany.zendesk.com]/tickets/98432'
}

// ─────────────────────────────────────────────────────────────────
// STEP 6: Customer acknowledgement email via Gmail
// ─────────────────────────────────────────────────────────────────
Gmail.POST /gmail/v1/users/me/messages/send {
  to      : 'customer@example.com'
  subject : 'We received your request [Ticket #98432]'
  body    : 'Hi Alex, thanks for getting in touch. We have received
             your request and our team will respond within 4 hours.
             Reference: #98432.'
}

// ─────────────────────────────────────────────────────────────────
// ON ANY DOWNSTREAM FAILURE (Slack or Gmail)
// ─────────────────────────────────────────────────────────────────
LOG {
  error_log.event     : 'slack_failed' | 'gmail_failed'
  error_log.ticket_id : '98432'
  error_log.timestamp : datetime
}
Slack.POST fallback_alert -> #support-ops | Team Lead DM
// ─────────────────────────────────────────────────────────────────
// END OF AUTOMATED CYCLE
// Total automated elapsed time: target < 90 seconds from webhook
// ─────────────────────────────────────────────────────────────────