Skip to main content
A wallboard alarm rule tells the supervisor wallboard when to escalate a queue metric from a stat into an alarm — for example, “the longest wait on Support exceeds 120 seconds”, or “tenant-wide service level drops below 80%”. Rules are evaluated every five seconds, fire while a breach persists, and clear automatically when the metric recovers. Wire the rules you want supervised, tune them over time, and delete the noise. Base path: /api/v1/voice/wallboard/alarm-rules Scope: voice read to list; voice write to create, update, and delete.

​
The shape of a rule

Every rule has a metric, a comparator, and a threshold, plus a few optional fields:
  • queue_id — the queue this rule watches. Omit it (or send null) for a tenant-wide rule that applies to every queue. Tenant-wide rules are handy for org-level cutoffs like “service level below 80% anywhere”.
  • name — a label you recognise on the wallboard (1–120 characters).
  • metric — one of:
    • waiting — callers currently waiting in the queue
    • longest_wait — current oldest caller’s wait, in seconds
    • avg_wait — average wait across waiting callers, in seconds
    • predicted_wait — the dispatch engine’s predicted wait for a caller entering now (longest current wait plus the typical handle time), in seconds
    • agents_available — agents who can take the next call right now
    • agents_total — agents on the roster for the queue
    • service_level — SL achievement percentage, computed over a rolling 30-minute window
    • abandoned_rate — abandoned-call percentage, computed over a rolling 30-minute window
  • comparator — one of gt, gte, lt, lte, eq.
  • threshold — the numeric boundary the comparator evaluates against. For a percentage metric (service_level, abandoned_rate) send a fraction from 0 to 1 (send 0.8 for 80%); for the wait-time metrics it is seconds.
  • duration_seconds — how long the breach must persist before the alarm fires. 0 (the default) fires on the first breaching tick; anything up to 86,400 (24h) is accepted.
  • channel — how the alarm surfaces: sse (default, live wallboard events), sse+notification (also a browser notification), webhook, or email.
  • enabled — set it false to mute a rule without deleting it (defaults to true).
Both an alarm and its recovery state are evaluated against live queue stats; service_level and abandoned_rate are the only metrics backed by a rolling window (30 minutes). A rule on either of them is skipped on any tick where the window carried no traffic, rather than firing on a meaningless 0%.

​
Create a rule

cURL
201 returns the created rule row. When a rule with the same queue_id, metric, comparator, and threshold already exists, the conflict resolves to the existing row with 200 — a double-click does not create a duplicate.

​
List and filter rules

cURL
200 returns every rule for the tenant. Pass queue_id to narrow to the rules actually evaluated for that queue — its queue-scoped rules plus the tenant-wide rules, which is exactly the set the evaluator applies. Each rule in the response carries its id, the resolved queue_id / queue_name (null for tenant-wide), name, metric, comparator, threshold, duration_seconds, channel, enabled, the creator’s created_by_user_id, and created_at / updated_at timestamps.

​
Update a rule

Patch the fields you want to change; at least one field is required. Send queue_id: null to move a queue-scoped rule to tenant-wide.
cURL
200 returns the updated rule row; 404 when no rule with that id exists; 409 when the edited shape collides with another rule.

​
Delete a rule

Hard-remove a rule; the wallboard stops raising it at the next evaluation.
cURL
204 on success, 404 when the id is unknown. Deletion is permanent — if you want to silence a rule temporarily, set enabled: false instead.

​
Evaluation lifecycle

A background evaluator ticks every five seconds — the same cadence the live wallboard refreshes on — and evaluates every rule for every tenant on every tick. Per tick, per queue, the applicable rule set is the queue-scoped rules plus every tenant-wide rule (exactly what a queue_id-filtered list call returns). A rule change you push with PATCH takes effect within five seconds of the next tick. What duration_seconds means precisely: with 0, the alarm fires on the first tick where the condition holds. With any value above 0, the condition must hold continuously for that many seconds — the breach timer starts on the first breaching tick, and a single non-breaching tick resets it. Only once the timer elapses does the alarm fire. This is what filters out momentary spikes: a rule that would otherwise flap on a single tick instead demands a sustained breach.

​
Alarm lifecycle

  1. Armed — the rule is being evaluated on every tick.
  2. Breaching — the condition holds but duration_seconds has not yet elapsed; nothing is shown to supervisors.
  3. Fired — the duration gate has elapsed and the alarm surfaces. A breach that persists re-fires at most once every 30 seconds per (queue, rule), so a stuck queue produces a fresh event rather than a flood.
  4. Recovered — the moment the metric returns to the comparator-safe side, the alarm stops re-firing, the breach timer is reset, and a future breach starts the duration clock fresh.
An alarm clears automatically on recovery — there is no explicit acknowledge/clear action, and no adjacency counted for supervisors to chase. The wallboard’s live feed receives each fired event; sse+notification additionally raises a browser notification so a backgrounded tab still pages the supervisor. Recovery means silence, not a persistent badge.

​
Choosing thresholds

Two worked examples — a tenant-wide staffing floor and a queue-level wait guard: Tenant-wide service-level floor. Watch the org-wide SL and page when it drops:
Because service_level is a rolling 30-minute figure, a long duration_seconds (10 minutes here) keeps the alarm from firing on a thin early-morning window. Queue-level wait guard. Watch a single queue for callers waiting too long:
Avoid a bare longest_wait threshold on queues that absorb overflow calls by design — those callers arrive already holding accumulated wait, so every overflow arrival trips the alarm. Use avg_wait or a higher longest_wait threshold on overflow-absorbing queues.

​
Choosing a channel

All four channel values still emit the same live wallboard.alarm_triggered event to the in-app wallboard feed; the channel field controls where the alarm additionally lands when the supervisor is off the wallboard tab:
  • sse — live feed only. Best for rules a supervisor watches on a mounted wallboard.
  • sse+notification — live feed plus a browser notification (if the supervisor has granted permission). Pick this when the wallboard might be backgrounded.
  • webhook — additionally POSTs the alarm to every webhook subscription registered for the wallboard.alarm_triggered event. Use this to drive PagerDuty/Opsgenie-style paging or a chat-ops script. The delivered body is a standard signed envelope wrapping the alarm payload:
Webhook body
  • email — additionally sends an immediate email to the organization’s admin users, subject “Queue alarm: <queue name> — <rule name>”, body describing the metric, comparator, threshold, and current value (percentages are rendered as whole numbers, so abandoned_rate at threshold 0.05 currently at 0.07 reads “abandoned_rate ≥ 5% breached — current value 7%”). Use this for breach classes an on-duty ops-bridge list should page on.

​
Troubleshooting

The alarm never fires. Check in order:
  1. The rule’s enabled flag — a muted rule is loaded by list calls but skipped by the evaluator.
  2. The scope — a queue-scoped rule cannot fire on queue B when its queue_id points at queue A; tenant-wide rules have queue_id: null. List with ?queue_id= for the queue you expect to fire on and confirm the rule appears.
  3. duration_seconds — a long window means the breach must hold continuously before anything fires; a short-lived spike never clears the gate.
  4. Comparator/threshold orientation — lt on service_level with threshold: 80 never fires because service_level thresholds are fractions in 0..1 (correct: threshold: 0.8). Verify the threshold you stored with a GET list call.
  5. Metric resolvability — rules on service_level / abandoned_rate skip ticks where the 30-minute window carried no traffic (that’s by design, to avoid firing on a fabricated 0%).
The alarm fires constantly. The breach is re-firing at most once every 30 seconds while it persists — if that’s too noisy, raise duration_seconds so only sustained breaches fire, loosen the threshold, or mute the rule with enabled: false while you retune. If the underlying metrics themselves look wrong (impossible SL percentages, waits that don’t match the floor), check the voice call quality troubleshooting guide before retuning thresholds against bad data.

​
Governance

Creating, updating, and deleting rules requires the voice write scope; listing requires voice read. Rule changes take effect within one evaluation tick. Prefer soft-delete (enabled: false) when you want to silence a rule you may need again — a seasonal staffing alarm, a queue you’re about to restructure. Use DELETE for rules created in error or permanently obsolete; deletion is hard, and the audit value lies in keeping the rule’s shape retrievable from list history rather than recreating it. For percentage metrics, always confirm the stored threshold is the 0..1 fraction form before attributing an alarm gap to rule logic — a stored 80 reads to evaluators as “breach only if service level falls below 8000%,” which is unreachable.