omnichannel-helpdesk-ticket-routing

Omnichannel Helpdesk & Ticket Routing Skill Guide

This skill provides architectural patterns, state machine designs, and automated routing logic for high-volume customer support operations.

---

1. Ticket Lifecycle & Routing State Machine

[ Incoming Ingestion ] (Email / Chat / WhatsApp / Webhook)
             |
             v
[ Normalization & Deduplication Layer ]
             |
             v
[ Ticket Classifier & SLA Policy Attacher ]
  |-- Calculate Response SLA (e.g., P1 = 15m, P2 = 1h, P3 = 4h)
  |-- Tag Tier: VIP / Standard
             |
             v
[ Skill-Based Routing Engine ]
  |-- Match Agent Language, Product Domain, and Shift Status
  |-- Distribute via Round-Robin or Least-Loaded Capacity
             |
             v
[ Assigned to Agent / Auto-Resolved via AI Assistant ]

---

2. Production Code Implementations

A. Skill-Based Round-Robin Routing Engine (Python)

from dataclasses import dataclass, field
from datetime import datetime, timezone
from enum import Enum
import heapq


class Priority(Enum):
    URGENT = 1
    HIGH = 2
    NORMAL = 3
    LOW = 4


@dataclass
class Agent:
    id: str
    name: str
    skills: set[str]
    active_ticket_count: int = 0
    max_capacity: int = 5
    is_online: bool = True

    def is_eligible(self, required_skills: set[str]) -> bool:
        return self.is_online and (self.active_ticket_count < self.max_capacity) and required_skills.issubset(self.skills)


@dataclass
class Ticket:
    id: str
    priority: Priority
    required_skills: set[str]
    customer_id: str
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
    assigned_agent_id: str | None = None


class TicketRouter:
    def __init__(self, agents: list[Agent]):
        self.agents = agents

    def route_ticket(self, ticket: Ticket) -> Agent | None:
        """Finds eligible agent with minimum active ticket count (Least-Loaded)."""
        eligible_agents = [
            agent for agent in self.agents
            if agent.is_eligible(ticket.required_skills)
        ]

        if not eligible_agents:
            return None  # Enqueue to backlog / fallback queue

        # Sort by active tickets ascending
        selected_agent = min(eligible_agents, key=lambda a: a.active_ticket_count)
        selected_agent.active_ticket_count += 1
        ticket.assigned_agent_id = selected_agent.id
        return selected_agent

B. SLA Breach Warning & Webhook Monitor (TypeScript / Node.js)

export interface SLAPolicy {
  p1MaxResponseMinutes: number; // e.g. 15
  p2MaxResponseMinutes: number; // e.g. 60
  p3MaxResponseMinutes: number; // e.g. 240
}

export function evaluateSLABreach(
  ticketPriority: "P1" | "P2" | "P3",
  createdAtIso: string,
  firstResponseAtIso: string | null,
  policy: SLAPolicy
): { isBreached: boolean; minutesRemaining: number } {
  const created = new Date(createdAtIso).getTime();
  const now = Date.now();
  const elapsedMinutes = (now - created) / (1000 * 60);

  const limitMinutes =
    ticketPriority === "P1"
      ? policy.p1MaxResponseMinutes
      : ticketPriority === "P2"
      ? policy.p2MaxResponseMinutes
      : policy.p3MaxResponseMinutes;

  if (firstResponseAtIso) {
    const respondedTime = (new Date(firstResponseAtIso).getTime() - created) / (1000 * 60);
    return { isBreached: respondedTime > limitMinutes, minutesRemaining: 0 };
  }

  const minutesRemaining = limitMinutes - elapsedMinutes;
  return {
    isBreached: minutesRemaining <= 0,
    minutesRemaining: Math.round(minutesRemaining),
  };
}

---

3. Best Practices Checklist

• [ ] Deduplication: Generate a deterministic message hash of (customer_id, normalized_subject, last_message_body) within a 5-minute sliding window to prevent duplicate tickets from webhook flurries.
• [ ] Graceful Degraded Routing: If no agent matching required skills is available, escalate to a generic Senior Tier 1 triage group rather than stalling in limbo.
• [ ] SLA Pause Conditions: Automatically pause SLA countdown clocks when ticket status moves to "Pending Customer Information".