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