The voice supervisor plane

A supervisor on the voice floor has four ways to touch a live call or their whole queue — monitor, whisper, takeover, and announce — plus a set of read surfaces (live transcript, monitor-session ledger, omnichannel queue view) that tell them when an intervention is worth making. This page is the model for all of it, so the per-verb operator guides and troubleshooting pages stay procedural. Every verb in this plane is a control-plane action against an existing inbound call leg’s conference — it never touches the outbound path. Outbound MT voice and SMS exit only through the Devotel wholesale softswitch; nothing on this page wires a provider route.

1. The four supervisor scissors

Each verb answers “who hears what” differently. The route path is the public contract; pick the verb whose audio semantics match the intervention you need.

Verb	Who hears the supervisor	Who hears the agent	Who hears the customer	Route
Monitor (listen)	hears both agent and customer	nothing new	nothing new	`POST /api/v1/voice/supervisor/calls/{id}/monitor`
Whisper	heard by the agent only	hears the supervisor	conversation unchanged	`POST /api/v1/voice/calls/{id}/whisper`
Takeover (warm handoff)	heard by the customer (and agent during grace)	dropped after handoff	now talking to the supervisor	`POST /api/v1/voice/supervisor/takeovers`
Announce (queue-wide)	n/a (text broadcast to every agent in the queue)	reads a toast	nothing	`POST /api/v1/voice/supervisor/announce`

Monitor-in (listen). Audit-only passive listen — the supervisor’s leg joins the conference in listen mode, hearable by nobody. Used for quality sampling, compliance spot checks, and pre-whisper reconnaissance. Every open monitor session lands on the immutable per-tenant monitor-session ledger (see §5) with its own monitor action literal, so reporting separates passive listening from coaching verbs. Whisper-in. The supervisor speaks into the agent’s ear; the customer-side leg does not carry the supervisor’s audio. The agent keeps their customer conversation going while receiving coaching. On two-party-consent jurisdictions the platform can play a disclosure to the agent leg before the whisper opens (see the roles & permissions concept for where role disclosure flows are configured). Takeover (warm handoff). A state machine, not a single hook swap. The supervisor initiates with their own leg id and the agent’s leg id; an optional whisper_grace_seconds window (0–30s, default 5) lets the supervisor brief the agent before the customer’s audio moves. Once advanced to the terminal state, the agent’s leg is dropped and the supervisor owns the customer conversation. A whisper_mode flag bypasses the handoff entirely — coach-only audio, no agent-leg drop, terminal state whisper_only. Reasons are enumerated (manual default; other values such as escalation-driven) so takeover listings are reporting-safe. Read it back with GET /api/v1/voice/supervisor/takeovers and advance/cancel with PATCH /api/v1/voice/supervisor/takeovers/{id}. When a takeover fails mid-flight, the takeover failures troubleshooting page is the diagnosis surface. Announce (queue-wide). Not an audio splice at all — a text (plus optional hosted audio URL) broadcast pushed to every agent subscribed to a given queue. The supervisor posts POST /api/v1/voice/supervisor/announce with {queueId, text, severity, audioUrl?}; severity is info / warning / critical so the agent’s toast is coloured correctly in an SLA storm. Agents receive the frame over the GET /api/v1/voice/supervisor/announce/stream SSE channel, filtered to their queue memberships, using a short-lived ticket from POST /api/v1/voice/supervisor/announce/ticket instead of a long-lived API key on the URL. Text is bounded (280 chars — the SMS-chapter bound).

The whisper-text backchannel (§4) and the queue-wide announce broadcast are both silent, control-plane deliveries into the agent’s UI — neither joins the audio bridge. Choose them when “make the agent flinch” is the wrong outcome.

2. The omnichannel supervisor queue view

GET /api/v1/voice/supervisor/omnichannel-queue blends the two queue shapes the ACD queue model defines — voice queue entries and digital (inbox) queue work items — into one position-ordered list:

{
  "entries": [
    {
      "workItemId": "…",
      "channelKind": "voice",
      "channelSlug": "…",
      "position": 1,
      "effectivePriority": 0,
      "waitSeconds": 183,
      "slaSeconds": 300,
      "slaBreached": false
    }
  ],
  "generatedAt": "2026-09-18T13:55:00Z"
}

Both halves of the blend are bounded reads (voice rows capped, digital served by the same backpressure-capped service the digital-ACD metrics use), so a large backlog degrades to a truncated view, never an unbounded scan. The ordering is the same wait/SLA/priority ranking the blended dispatcher reads — the supervisor sees the queue in dispatch order, not in raw FIFO. This is a rendering surface only: it exposes “who is waiting, in what order” and performs no routing decision and no signalling.

3. Escalation rules — arming a verb without a human click

Operator-initiated verbs require someone to press the button. The escalation evaluator decides, on each live-call signal tick, whether a supervisor should be pulled in and with which verb — then arms a directive the supervisor-assist stream surfaces. It never bridges a leg unattended. A rule is a small declarative object:

{
  "id": "esc_angry-caller",
  "name": "Angry caller — whisper me in",
  "enabled": true,
  "when": {
    "sentimentBelow": -0.6,
    "distressStreakAtLeast": 2
  },
  "verb": "whisper",
  "cooldownSeconds": 120
}

Signals are the live per-call snapshot: rolling caller sentiment (−1…1), wait seconds, the consecutive negative-copilot-card streak, the latest CSAT estimate (0…1), and the supervisor copilot’s recommended action. Every present condition must hold (logical AND).
Fail-safe on missing data — a condition referencing a null signal does not fire. The engine never auto-pulls on a guess.
Verb set — only listen, whisper, barge are auto-armable; takeover is deliberately excluded because replacing the agent needs a human in the loop. When multiple rules fire on one tick, the most intrusive verb wins (listen < whisper < barge) so the floor never gets a contradictory pair.
Cooldown — a per-rule re-fire suppression window (default 120s) so a sustained bad sentiment does not spam the wallboard.

Rules pair naturally with the per-queue SLA forecast ladder described in Per-queue SLA breach alerting and escalation policies: the SLA ladder escalates queue-level risk; the evaluator escalates a single live call in real time.

4. The whisper-text backchannel

POST /api/v1/voice/supervisor/calls/{id}/whisper-text sends a silent, text-only coaching tip to the agent’s UI overlay — no audio bridge, no whisper-mode SIP redirect, no caller-audible footprint. This is the sister surface to the audio whisper verb, for the “nudge mid-sentence without making the agent flinch” case:

{ "text": "Ask for the account's billing email before proceeding.", "display_ms": 8000 }

text is bounded (≤500 chars) and HTML-stripped server-side.
display_ms (1000–30000, default 8000) pins how long the overlay stays up — capped so a stale tip cannot occupy the agent’s screen.
Delivery is live-only: the tip is published on the tenant events channel without replay decoration, so a reconnecting agent does not have yesterday’s tips re-surface.
A curated library of vetted snippets backs the drop-down the supervisor picks from — GET/POST /api/v1/voice/supervisor/coaching-templates (create/edit/archive) — so floor coaching survives shift changes and stays on-brand. Owner and admin hold the CRUD; every mutation is audit-logged.

The response reports published: false when the agent’s UI has no active subscriber (off-shift or offline), so the wallboard renders an “agent offline” cue rather than a false “delivered” toast.

5. The supervisor transcript stream and the monitor-session ledger

Live transcript. GET /api/v1/voice/supervisor/calls/{callId}/transcript/stream is the supervisor-facing sister of the agent’s own call transcript stream. It subscribes to the same per-call transcript channel as the call-owning agent — one publisher contract — but differs in two deliberate ways:

Authorization — the agent stream serves the call-owning agent; the supervisor stream requires the supervisor role gate (see §6) and, for queue calls, per-supervisor queue scoping. All authorization resolves before the SSE handshake opens, so a denied request returns a clean JSON 403, never a half-opened stream.
Audience reason — the supervisor needs the transcript while deciding whether to whisper or barge; the agent needs the transcript of their own call. Same wire format, two distinct admission models, one redaction pipeline (live PII masking applied per the tenant’s compliance profile, identical to the agent-facing stream and the stored-recording redaction path).

Monitor-session ledger. Every audio verb and monitor open appends to an immutable per-tenant audit ledger. GET /api/v1/voice/supervisor/monitor-sessions reads it back with cursor pagination (keyset on started_at + id so ties never duplicate rows) and composable filters — call_id, supervisor_user_id, agent_user_id, action (listen / whisper / barge / coach / monitor / unlisten), and open_only=1 for the “who is monitoring right now” set. Each row carries open: boolean resolved server-side, so a wallboard’s “actively monitored” badge stays server-true. An empty result returns 200 with items: [] — a tenant with zero sessions is a valid posture, not a lookup failure.

6. Permissions — which role unlocks which scissor

Two gates stack. The route layer admits a role set; a second per-supervisor queue-scope gate then narrows the supervisor role to the queues they actually manage.

Surface	Role gate	Queue-scope gate for `supervisor`
Live verbs (listen / whisper / barge / monitor)	owner / admin / supervisor / superadmin	Gated against the queue mapping when the call carries a queue
Takeovers	owner / admin (people-management surface)	Service-level queue scoping applies to supervisor-initiated handoffs
Announce / coaching templates	owner / admin	n/a (broadcast targets a whole queue)
Omnichannel queue view, monitor-session ledger, supervisor transcript stream	owner / admin / supervisor / superadmin	`supervisor` role scoped to mapped queues; owner/admin/superadmin bypass with blanket visibility

A call with no queue on its metadata (non-ACD direct-dial) falls through the queue gate to plain tenant scoping — consistent across the whisper-text, transcript-stream, and takeover surfaces. The supervisor role is fail-closed: zero queue mappings means zero visible queue calls. The full role taxonomy is on Roles, teams & permissions.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

The voice supervisor plane: monitor, whisper, takeover, and announce

The voice supervisor plane

1. The four supervisor scissors

2. The omnichannel supervisor queue view

3. Escalation rules — arming a verb without a human click

4. The whisper-text backchannel

5. The supervisor transcript stream and the monitor-session ledger

6. Permissions — which role unlocks which scissor

Further reading

​The voice supervisor plane

​1. The four supervisor scissors

​2. The omnichannel supervisor queue view

​3. Escalation rules — arming a verb without a human click

​4. The whisper-text backchannel

​5. The supervisor transcript stream and the monitor-session ledger

​6. Permissions — which role unlocks which scissor

​Further reading

The voice supervisor plane

1. The four supervisor scissors

2. The omnichannel supervisor queue view

3. Escalation rules — arming a verb without a human click

4. The whisper-text backchannel

5. The supervisor transcript stream and the monitor-session ledger

6. Permissions — which role unlocks which scissor

Further reading