Skip to content

hamzabellouch/agent-skills / Business/Customer_Operations_and_Support/omnichannel-helpdesk-ticket-routing

omnichannel-helpdesk-ticket-routing

Verified

Architect automated omnichannel helpdesk routing and SLA lifecycle engines across email, chat, SMS, and webhooks. Integrate with ticketing systems (Zendesk, Freshdesk, Jira Service Management), enforce strict SLA tier policies (response time, resolution time), implement skill-based agent routing, and manage ticket state machines. Trigger when building customer service backends, routing algorithms, or support automation systems.

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".
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall