Omnichannel queue routing for digital channels

Omnichannel queue routing decides which agent (or overflow bucket) an inbound digital conversation lands with — chat, email, WhatsApp, SMS, RCS, social, and the APAC OTT channels — using the same skill-queue machinery your voice queues already use. Voice covers the PSTN/call leg; digital covers the inbox. This guide walks the operator loop for digital channels: model queues, attach attribute and affinity policies, preview SLA behavior before a conversation arrives, and verify the decision in analytics. Inbound routing decides where a conversation enters; digital queue routing decides who answers it once it is in the inbox. Outbound messaging and voice termination are unaffected — none of these controls change how outbound calls or messages are placed; they govern inbound queueing and assignment only. Outbound MT voice and SMS continue to exit exclusively through the Devotel wholesale softswitch — these routes are tenant-owned inbound routing config, never a provider-side or carrier-side signalling change. Every control here is tenant-owned: queue definitions, attribute rules, affinity weights, SLA targets, and overflow actions live in your organization’s settings and take effect on the next inbound item. Suppression and quiet-hours are honored the same way they are for messaging; routing does not bypass DNC or consent gates. Base paths: /api/v1/inbox and /api/v1/voice Authentication: Clerk session (Authorization: Bearer <token>) or API key (X-API-Key). Scope: write operations require an owner or admin role (voice:write scope on the API-key route, plus the inbox surface for digital queues); reads require a signed-in session or API key. Supervisors reach the queue-monitoring surfaces.

1. Concepts — digital queues vs voice queues

A voice queue (/api/v1/voice/queues) is an ACD target for PSTN and in-app voice: callers wait in FIFO, the platform dispatches to an eligible available agent, and overflow plays out as voicemail / forward / disconnect. A digital queue (/api/v1/inbox/digital-queues) routes inbox conversations through the same skill-match / SLA / overflow machinery but the work item is a conversation thread on a digital channel, not a call leg. The two models differ in the places a CCaaS operator cares about:

	Voice queue	Digital queue
Item	a call leg (`acd_call_queue_entries`)	a conversation (per-queue Redis waiting set)
Channel	`voice` (and video)	`email`, `web_chat`, `whatsapp`, `sms`, `rcs`, `viber`, `instagram`, `messenger`, `line`, `telegram`, `apple_messages`, `kakao`, `zalo`, `wechat`
Overflow actions	voicemail, forward, disconnect, callback	`routing_rules` (fall back to the org inbox routing-rules engine), `overflow_queue` (chain into another digital queue), `auto_responder`, `hold`
Storage	one row per queue in the tenant ACD tables	JSONB array in `organizations.settings.digital_acd_queues`
SLA timers	`max_wait_seconds` per queue	`sla_seconds` per queue; the SLA sweep re-evaluates waiting items past their deadline

Voice and digital queues converge at the monitoring surface: the omnichannel queue view (GET /api/v1/voice/supervisor/omnichannel-queue) blends both backlogs into ONE position-numbered, wait/SLA/priority-ordered list — the same ordering the routing engine assigns by — so a supervisor sees the shared queue, not two silos.

2. Attribute routing and affinity rules

Before a work item ever enters a queue, two optional server-side policies can reshape it. Both are opt-in (each disabled by default) and both operate on the inbound conversation’s contact attributes and the agent roster — never on outbound signalling.

Attribute routing

GET / PUT /api/v1/voice/attribute-routing reads and replaces your attribute-routing policy: an ordered list of rules that append extra requiredSkills and an optional priorityBoost to a queue entry based on the contact’s tags and CDP attributes. Storage is a single JSONB key (organizations.settings.acd_attribute_routing), so a change takes effect on the next enqueue with no migration. A rule has the shape:

{
  "kind": "tag",
  "value": "vip",
  "extraSkills": ["vip-handler"],
  "priorityBoost": 5,
  "label": "VIP tier"
}

Rule kinds (validated by the server, hard-capped at 50 rules per tenant, 16 extra skills per rule):

`kind`	Required field(s)	Effect	Example
`tag`	`value`	Contact carries the tag	`value: "vip"`
`attribute_equals`	`key`, `value`	Contact attribute equals the value	`key: "language"`, `value: "es"`
`attribute_gte`	`key`, `threshold`	Numeric attribute meets the threshold	`key: "account_value"`, `threshold: 50000`

extraSkills entries are validated against your tenant’s active skill catalog — an unknown skill slug returns 422 UNKNOWN_SKILL instead of being persisted. priorityBoost is an integer from 0 to 99 (rejected out of range), and label is a free-text operator name shown in the settings panel. Replace the policy from the dashboard at Settings → Voice → Attribute routing (no JSON editing), or over the API with a full-document PUT:

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/attribute-routing" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "rules": [
      { "kind": "tag", "value": "vip", "extraSkills": ["vip-handler"], "priorityBoost": 5, "label": "VIP tier" },
      { "kind": "attribute_equals", "key": "language", "value": "es", "extraSkills": ["spanish"] },
      { "kind": "attribute_gte", "key": "account_value", "threshold": 50000, "extraSkills": ["enterprise"], "priorityBoost": 3 }
    ]
  }'

The write is a surgical JSONB update, so a concurrent edit to a different settings key can never be clobbered, and the change is written to your audit log.

Affinity routing

GET / PUT /api/v1/voice/affinity-routing reads and replaces your behavioral affinity config: the pairing objective that routes an inbound contact to the agent best-matched to them (customer-segment ↔ agent-affinity fit) rather than the globally best-scoring agent. Storage is organizations.settings.acd_affinity_routing; both writes are audited.

{
  "enabled": true,
  "treatment_percent": 100,
  "affinity_weight": 0.75,
  "headroom_weight": 0.25,
  "agent_profiles": {
    "user_2bFzq9W": ["segment:enterprise", "style:analytical"]
  }
}

enabled — opt-in; defaults to false. A malformed or disabled config resolves to the safe disabled default in the router.
treatment_percent — share of eligible queue items (0–100) routed on the affinity arm. Ramp the rollout instead of flipping globally.
affinity_weight / headroom_weight — server-clamped to 0–1; the pair balances contact↔agent fit against agent headroom.
agent_profiles — map of Clerk user id to affinity tags the agent pairs well with, e.g. segment:enterprise, style:analytical.

Affinity tuning is supervisor/admin-managed from the same Settings → Voice surface, layered under the queue’s own skills. It never decides a destination (queue or overflow); it decides which eligible agent an already-created work item pairs with, on the same live candidate snapshot the voice ACD uses, so voice and digital share one candidate pool.

3. Routing-rules evaluator

Once a conversation arrives in the inbox, the routing-rules engine (/api/v1/inbox/routing-rules) assigns it. Rules are evaluated in priority order (lower priority first, firewall-style first-match-wins) and AND-combine their conditions.

Conditions

Condition	Shape	What it matches
Channel	one channel from the digital enum	`whatsapp`, `email`, `web_chat`, …
Skill	a skill slug in your tenant catalog	`spanish`, `billing`
Language	ISO 639-1 from the built-in detector	`es`, `de`
Sentiment	`positive` / `neutral` / `negative`	inferred live signal
Contact attribute	equals / greater-than / contains	any CDP attribute
Business hours	in-window / out-of-window (+ holidays)	your schedule
Queue depth / wait / AHT / agents available	numeric	live queue telemetry

Actions

Action	Effect
`assign_user`	assign to one specific user
`assign_team`	assign to a team
`assign_round_robin`	balance across a pool
`assign_skill_based`	pick the org user whose skills best match the rule’s `required_skills`; falls back to round-robin on no overlap
`set_tag`	tag the conversation
`set_priority`	raise/lower queue priority (`urgent` / `high` / `normal` / `low`)
`trigger_agent`	hand to an AI agent

Create a rule dynamically over the API:

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/inbox/routing-rules" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WhatsApp Spanish → LATAM pod",
    "priority": 10,
    "conditions": [
      { "kind": "channel", "value": "whatsapp" },
      { "kind": "language", "value": "es" }
    ],
    "actions": [
      { "kind": "assign_skill_based", "required_skills": ["spanish"] },
      { "kind": "set_tag", "value": "latam" }
    ]
  }'

A digital queue’s overflow_action: "routing_rules" falls back to this same engine — so a queue that cannot place an item never silently hijacks the conversation; it defers to the universal escape hatch.

4. On-queue SLA forecast preview

After an item joins a queue (digital or voice), the SLA forecast estimates breach-before-answer and suggests the callback/overflow capacity that absorbs the backlog before the SLA lands. This is advisory — no dispatch fires from the preview. POST /api/v1/voice/queues/:id/sla-forecast takes a live queue snapshot and returns the forecast. The response tells you the expected head-of-line wait, the projected breach over the queue’s SLA threshold, and how much callback capacity would absorb the backlog pre-breach — so a supervisor sees “offer 3 callback slots” before the wallboard turns red, not after.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc123/sla-forecast" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "offeredCalls": 42,
    "answeredWithinSla": 27,
    "shortAbandons": 2,
    "currentDepth": 9,
    "oldestQueuedSeconds": 84,
    "agentsAvailable": 3,
    "avgHandleSeconds": 305,
    "windowMinutes": 15
  }'

The server resolves the queue’s SLA target from your persisted policy (body fields override when present); the forecast itself is a pure, dependency-free module that the wallboard tick reuses, so the preview and the live supervisor surface cannot drift. The SLA-forecast paired with the queue SLA escalation policies covers the full pre-breach → post-breach loop.

5. Verification — queue analytics stream

Every routing decision lands in observable queues. Three read-only surfaces let you verify end to end:

GET /api/v1/voice/queues/:id/analytics — aggregated per-queue metrics (offered/answered, service-level rate, ASA, AHT, abandon rate) against your SLA target. Use this to confirm a rule change actually shifted the numbers you intended.
GET /api/v1/voice/supervisor/omnichannel-queue — the blended voice + digital backlog as one position-numbered, wait/SLA/priority-ordered list. Confirm the item that should sit at position N actually does, and that a priorityBoost rule bumps a VIP chat above older normal-priority items.
Queue live SSE stream (GET /api/v1/voice/queues/:id/live) — Server-Sent Events pushing real-time queue state every 5 s (keepalive every 15 s, sessions capped at 30 min, hard-capped to 100 concurrent connections per tenant). Subscribe while you toggle a rule and watch the queue respond — the stream is tenant-scoped and CORS-locked to trusted origins.

cURL

curl -N "https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc123/live" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream"

Combine the three for the operator loop: change an attribute or affinity rule, watch the live stream pick the item up in the blended queue, then read the analytics endpoint to confirm the SLA/ASA shift you expected. For digital channels, also check the per-queue live metrics (GET /api/v1/inbox/digital-queues/:id) — one queue’s waiting / assigned / sla_breached counters, mirroring the voice surface. Next steps: Set up and run voice queues for the voice-side counterpart, Inbox setup to wire the inbox’s digital channels, Queue SLA escalation policies, and Supervisor live monitoring — digital for the blended supervisor surface.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Omnichannel queue routing for digital channels

1. Concepts — digital queues vs voice queues

2. Attribute routing and affinity rules

Attribute routing

Affinity routing

3. Routing-rules evaluator

Conditions

Actions

4. On-queue SLA forecast preview

5. Verification — queue analytics stream

​1. Concepts — digital queues vs voice queues

​2. Attribute routing and affinity rules

​Attribute routing

​Affinity routing

​3. Routing-rules evaluator

​Conditions

​Actions

​4. On-queue SLA forecast preview

​5. Verification — queue analytics stream

1. Concepts — digital queues vs voice queues

2. Attribute routing and affinity rules

Attribute routing

Affinity routing

3. Routing-rules evaluator

Conditions

Actions

4. On-queue SLA forecast preview

5. Verification — queue analytics stream