> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> The four live-call intervention verbs a supervisor can run — silent monitor, agent-only whisper, full takeover, and queue-wide announce — plus the omnichannel queue view, auto-escalation rules, the whisper-text backchannel, the supervisor transcript stream, and the role/queue-scope permissions that gate each surface.

# 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](/concepts/roles-teams-permissions) 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](/troubleshooting/supervisor-takeover-failures) 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).

<Note>
  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.
</Note>

## 2. The omnichannel supervisor queue view

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/voice/queue-sla-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:

```json theme={null}
{ "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:

1. **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.
2. **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](/concepts/roles-teams-permissions).

## Further reading

* [The ACD queue model](/concepts/acd-queue-model) — presence, dispatch, and overflow the supervisor is watching.
* [Quality evaluation lifecycle](/concepts/quality-evaluation-lifecycle) — post-hoc scoring that consumes monitoring output.
* [Roles, teams & permissions](/concepts/roles-teams-permissions) — full role/scope model.
* [Per-queue SLA breach alerting](/voice/queue-sla-escalation-policies) — the queue-level escalation ladder.
* [Voice queues guide](/guides/voice-queues) — the setup walkthrough for the queues this plane supervises.