​

Per-digital-queue inbox SLA escalation policies

• Workspace SLA policies (Inbox SLA timers) hang first-response, next-response, and resolution clocks on individual conversations and fire breach tiers as each clock crosses a percentage of its target. They answer: this conversation waited too long.
• Per-digital-queue escalation policies (this page) watch the queue as a whole: how many open conversations in it already breached, and how old the oldest still-open conversation is. They answer: this queue is stalling — page someone now.

​

The per-queue policy shape

• breachAction — the one-shot response when no ladder is configured: notify_supervisors (org admins see a bell/email notification), page_supervisor (the outbound tenant webhook your paging tool subscribes to), both, or none (record-only — the breach event is still logged).
• escalationSteps[] — the ladder, up to 20 rungs. Once any rung exists the ladder wins and the single-shot action is ignored — the same supersession rule the voice ladder and the workspace SLA tiers use. Rungs at delayMinutesAfterBreach: 0 fire the instant the scan records a breach; delayed rungs are fired afterward by the scheduled executor while the queue still hasn’t recovered. Step actions reuse the workspace breach-action vocabulary — notify, reassign, slack_alert, slack_webhook, teams_webhook, webhook, none — so a supervisor who already runs conversation-level SLA tiers is composing the same building blocks against a queue clock.

​

Scan and events API

curl -X POST "https://api.orbit.devotel.io/api/v1/inbox/digital-queues/q_whatsapp_support/sla-escalation/scan" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "breachedConversations": 4, "oldestWaitSeconds": 260 }'
# -> { "queue_known": true, "policy_configured": true, "breached": true,
#      "event_logged": true, "cooldown_active": false,
#      "alert_fired": ["bell", "webhook"], ... }

curl -X GET "https://api.orbit.devotel.io/api/v1/inbox/digital-queues/q_whatsapp_support/sla-escalation/events?limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

​

Configure the policy from the dashboard

1. Enable the policy and set the gates. The master switch, the breached-conversation severity floor, the oldest-wait buffer in seconds, and the cooldown. The wait gate is always “the queue’s own SLA seconds plus this buffer,” so edit the queue’s SLA target in the queue form and use the buffer here only to raise the gate — never to lower it.
2. Pick the single action, or add rungs to the ladder. The breach-action dropdown carries the four one-shot verbs; Add step opens a ladder rung with its action, optional config (webhook URL, supervisor user ids), and delay in minutes. The dialog states the supersession rule inline: when any rung exists, the ladder takes over from the single-shot action.
3. Read the breach history in place. The same dialog’s events table renders the newest-first log — timestamp, live counters, effective action, surfaces fired — so a policy change and its evidence sit on one screen.

​

End to end: a WhatsApp support queue

curl -X PUT "https://api.orbit.devotel.io/api/v1/inbox/digital-queues/q_whatsapp_support/sla-escalation/policy" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "breachedConversationThreshold": 2,
    "oldestWaitTickSeconds": 60,
    "breachAction": "none",
    "breachCooldownSeconds": 300,
    "escalationSteps": [
      { "stepIndex": 1, "delayMinutesAfterBreach": 0,
        "actionType": "notify",
        "actionConfig": { "user_ids": ["user_shift_lead"] } },
      { "stepIndex": 2, "delayMinutesAfterBreach": 15,
        "actionType": "webhook",
        "actionConfig": { "url": "https://paging.example.com/orbit/queue-sla", "secret": "whsec_your_signing_secret" } }
    ]
  }'

1. Steady state. The queue answers inside 120s. Your monitoring tick posts breachedConversations: 0, oldestWaitSeconds: 45 — no breach, a no-op, nothing logged.
2. The surge starts. A campaign lands and four conversations stack up; the oldest is 260 seconds old. The next scan posts breachedConversations: 4, oldestWaitSeconds: 260 — the wait gate (120 + 60 = 180s) trips and the severity floor (2) is met. The cooldown is clear, so the scan appends the breach, bells the shift lead (rung 1, delay 0), and posts the conversation.queue_sla_escalation webhook with the snapshot numbers. The event log records escalation_ladder as the route and ["bell", "webhook"] as the surfaces fired.
3. The repeat tick does nothing. Your loop scans again a minute later — same breach, but cooldown_active: true comes back and no second page goes out. One breach pages once.
4. Nobody fixes it for 15 minutes. The backlog is still deep, so the scheduled executor fires rung 2: the senior team’s paging endpoint receives the escalation webhook, and a supervisor reassigns two agents onto the queue.
5. Recovery. The wait collapses back under the gate; the scans turn to no-ops again. The breach log holds the full record for the QA review — observed counters, the route, and exactly which surfaces fired.

​

See also

• Inbox SLA timers — the workspace SLA engine: conversation-level first-response and resolution clocks, breach tiers, and acknowledgement.
• Per-queue SLA breach alerting and escalation policies (voice) — the voice sibling; the two pages share the action vocabulary and the ladder-wins rule, and differ in windows (voice evaluates percentage-over-window call aggregates; digital queues evaluate single-sample backlog gates).
• List digital ACD queues — queue CRUD and live queue stats the scan snapshot draws from.
• Webhook events — the conversation.queue_sla_escalation outbound webhook payload your paging tool consumes.