Skip to main content

​
Digital queues — skill-based ACD for the inbox

Digital queues are the inbox’s ACD (automatic call distribution) surface for non-voice channels. Where routing rules decide which facets a new conversation matches, a digital queue decides which agent the conversation lands with — the longest-idle operator whose skills cover the queue’s requirements — and what happens when no such agent is free. It is the digital counterpart of voice queues: same skill-match, SLA, and overflow machinery, applied to conversation threads instead of call legs. Queues govern inbound routing only. Nothing here changes how outbound messages or calls are placed; a queue never touches provider or carrier signalling.

​
Where the page lives

Open Inbox → Settings → Digital queues in the dashboard. The page lists every queue you have configured — name, channel, SLA target, required skills, overflow action, and an enabled toggle — and opens a create/edit form for each. You need an owner or admin role to see and manage the queue list. The same gate applies to the API: write endpoints (POST, PATCH, DELETE under /api/v1/inbox/digital-queues) reject any other role with 403 INSUFFICIENT_PERMISSIONS; signed-in members can read the list and the live metrics. A workspace may hold at most 200 queues. Everything on this page is tenant-scoped: queues live in your workspace’s own settings, and a queue in one workspace can never see or route another workspace’s conversations.

​
Create a digital queue

  1. Open Inbox → Settings → Digital queues and click Create queue.
  2. Name the queue for the intent, e.g. “Email support — tier 1”.
  3. Pick the channel the queue serves: email, web_chat, whatsapp, sms, rcs, viber, instagram, messenger, line, telegram, apple_messages, wechat, kakao, or zalo. The first enabled queue whose channel matches an inbound conversation takes it, so order queues deliberately when several serve the same channel.
  4. Set Required skills — agent tags from your workspace skill catalog. An agent is eligible only when their skills cover every skill you require; an empty list means any agent is eligible. Optionally set a Minimum skill level (1–5) when you track per-skill proficiency.
  5. Set the SLA target in seconds (up to 86,400 — one day). This is the time-to-assignment promise the queue holds a conversation to; the dashboard defaults to 300.
  6. Optionally cap Max queue depth (default 500) — the backpressure ceiling on the waiting set. A queue at its depth cap sheds immediately instead of holding.
  7. Choose the Overflow action — what the queue does when it cannot place a conversation (below). For overflow_queue, pick the target queue.
  8. Save, then enable the queue (queues are created enabled; toggle one off to pause routing without deleting it).
Equivalently, create over the API:
The response returns the queue with its assigned id, which you pass to PATCH /api/v1/inbox/digital-queues/:id for updates (PATCH only the fields you send; explicit null clears min_skill_level and overflow_queue_id) and DELETE /api/v1/inbox/digital-queues/:id to retire it. A malformed body gets 422 with the failing field named; the 200-queue ceiling returns 409 LIMIT_EXCEEDED.

​
How routing behaves

A digital queue evaluates each inbound conversation on its channel in three steps:
  1. Assign — if an eligible agent is available and has room under their per-channel cap, the conversation assigns immediately to the longest-idle such agent (ties break by lowest current open-conversation count). The agent gets a notification that the queue auto-assigned them.
  2. Wait — if no eligible agent is free right now, the conversation joins the queue’s waiting set with an SLA deadline stamped on it (now + sla_seconds). A scheduled sweep re-evaluates the set continuously: a conversation past its deadline assigns the moment an agent frees up, and only overflows when nobody is available at all.
  3. Overflow — the queue sheds the conversation per its action. Overflow fires for one of three reasons: queue_full (the depth cap), sla_breached (waited past the SLA target with still no eligible agent), or no_skilled_agents (nobody in the workspace holds the required skills — waiting is pointless, so it sheds immediately).
The four overflow actions: Use hold for asynchronous email queues where an indefinite wait is acceptable. Use overflow_queue for tiered escalation (tier 1 → tier 2). Leave the default routing_rules when your rules engine already encodes the fallback you want. A conversation a routing rule already claimed never enters a queue — the queue engine only picks up conversations still unassigned, so the two never fight over an item.

​
Composing queues with routing rules

Queues and rules are complementary, and the overflow handoff between them is explicit: overflow_action: "routing_rules" drops the conversation back to the same rules engine Routing rules manages, so an unplaceable conversation is never dropped or hijacked — it falls back to the universal evaluator. Rules decide who a conversation should route to; queues apply skill-match, SLA, and backpressure on top. For the full operator loop (attribute routing, affinity policies, and SLA forecasting before conversations arrive), see Omnichannel queue routing.

​
Live metrics

Two read-only endpoints expose each queue’s live state, and any signed-in workspace member can read them (metrics are deliberately wider than the admin-only write gate):
  • GET /api/v1/inbox/digital-queues/stats — one row per configured queue plus a workspace rollup: backlog (conversations waiting), oldest_wait (age of the longest-waiting conversation, in seconds), sla_breach_count (conversations past their SLA deadline), agents_available (available, skill-eligible operators — distinct operators in the rollup, not a per-queue sum), and virtual_holds (customers who asked to be messaged back).
  • GET /api/v1/inbox/digital-queues/:id/stats — the same snapshot for one queue; 404 when the id is not a configured queue.
The supervisor wallboard polls these on the same cadence as the voice board, so the digital floor and the voice floor read off consistent numbers. A transient backend issue degrades the board to zeros rather than an error.

​
Auditability

Every applied routing decision is recorded — arrival → wait → SLA breach → overflow or assign — with the queue, the decision kind, the reason an overflow fired, and the agent an assignment chose. Two read-only trails answer “why did this conversation land where it did”:
  • GET /api/v1/inbox/digital-queues/:id/decisions — the queue’s most recent decisions, newest first (up to 1,000; ?limit= defaults to 100), for distribution debugging and SLA attribution.
  • GET /api/v1/inbox/routing-decisions/:conversationId — one conversation’s chronological trail across every queue it passed through.
Queue configuration itself is auditable too: create, update, and delete each write to your workspace audit log with the acting user, the queue id, and the fields changed, so an owner can trace who retargeted a channel or relaxed a skill requirement.

​
Troubleshooting

Everything overflows immediately. The queue carries a skill requirement no agent in the workspace holds — fix it by adding the skill to an agent’s profile, or removing it from the queue (no_skilled_agents sheds without waiting). Check the workspace’s skill vocabulary first. Conversations wait but never assign. The eligible agents are present but at their per-channel conversation cap — the queue assigns only agents with headroom. Raise the cap, broaden the required-skills list, or add agents. A queue seems to do nothing. Two checks: it is enabled (a disabled queue stays in your list but never routes), and the inbound conversations’ channel slug matches the queue’s channel exactly. If a routing rule already assigned the conversation, the queue engine intentionally leaves it alone.