Skip to main content

​
Agent distress alert model

The distress button is the one-tap control an agent presses when a live caller turns threatening, abusive, or unsafe to handle alone. One press, POST /v1/voice/agents/me/distress, does three things: it records the incident in a per-tenant alert ledger, it flips the active call into a recorded state regardless of the queue’s recording policy, and it pages the linked supervisor over the same live event stream their wallboard already subscribes to. This page defines what qualifies an agent to raise it, the exact fail-open sequence, what the supervisor receives, how forced recording interacts with per-queue policy, and the audit and retention model for the alert row.

​
What the agent presses

The softphone renders a persistent panic control on the active-call screen. No confirmation dialog, no required reason field — a distress interaction is timed in seconds, not in form-filling. The agent can optionally pass a short free-text reason and a severity hint; both default sensibly when the press is a pure panic tap. An agent raises distress when a caller becomes hostile, issues a threat, demands escalation to a manager the agent cannot provide, or when the agent fears for the customer’s or their own safety. Nothing in the platform decides this — it is a human judgement call, and the model treats every press as valid. Because the endpoint is /me/, the agent’s identity comes from the authenticated session, never from a request field, so no agent can raise (or spoof) an alert on behalf of another. The request accepts three optional fields: Rapid duplicate taps are each their own ledger row — the supervisor surface deduplicates by alert id, so double-pressing never corrupts the feed.

​
The fail-open sequence

The sequence is ordered so the durable record always comes first, and every step after it degrades gracefully:
  1. Persist the alert row. The incident row is inserted into the tenant’s distress-alert ledger with a recording pending placeholder. If this insert fails, the request returns 500 and the softphone shows a retry — nothing else has happened yet, so nothing is half-applied.
  2. Force-enable recording. Once the row exists, the platform attempts to flip the active call into a recorded state. This is a best-effort external call, deliberately outside the database transaction: a missing call id, a call already in a terminal state, or a provider hiccup logs a warning and never blocks the alert.
  3. Stamp the recording outcome. A second short update patches the alert row with whether the recording flip succeeded and, if not, why — so the ledger carries the true recording state at the moment of distress, not a retroactive claim.
  4. Page the supervisor. A live event is published onto the omnichannel supervisor event stream as agent.distress.raised. The supervisor wallboard receives it within roughly 50–100 ms of the press.
  5. Append the audit entry. A tamper-evident audit row records the raise, after the recording outcome is known, so the audit trail always reflects final state.

​
What the supervisor receives

The supervisor wallboard subscribes to the per-tenant omnichannel capacity event stream. A distress press emits one frame on that stream with a stable event name: On receive, the wallboard sounds an audible alarm, flashes the affected agent’s tile, and re-fetches the distress feed. From there the supervisor acts with the live-monitoring controls — listen silently, whisper-coach, or barge into the call — covered in Supervisor live monitoring for voice and the supervisor view over voice agents.

​
Recording semantics

Queue recording policy decides whether an ordinary call records. A distress press overrides that decision for its call: the force-enable attempt runs regardless of the queue’s configured policy, because a threat interaction is exactly the audio HR or law enforcement later asks for. The override is per-call and one-directional — it turns recording on, never off, and it does not mutate the queue’s standing policy. The alert row’s detail payload captures both the outcome of the force-enable attempt (true, false, or skipped when there was no call) and whether recording was already active before the press. Compliance can therefore reconstruct the recording state at the moment of distress from the ledger alone. From that point the recording follows the ordinary pipeline — SIPREC ingest, upload, QC — and the ordinary state chain through retention. See Call recording pipeline and Recording lifecycle.

​
Why fail-open

The ordering is a deliberate design stance, and it protects the two parties who matter in a distress event: the agent and the eventual investigator. A flipped order — recording first, ledger second — would create a window in which a call was being recorded with no persisted justification for it, which is a consent and audit problem. The persisted alert row is the source of truth; the notification and the recording flip are degraded gracefully when their downstream is unavailable, because a lost notification is recoverable from the feed but a lost incident record is not. The one step that is allowed to fail loudly is the insert itself: when the ledger cannot take the row, the agent gets an explicit error and retries, rather than the press silently evaporating.

​
Audit and retention

Each raise also appends a row to the per-tenant audit ledger with the action agent.distress.raised, naming the agent, the call (falling back to the alert id when no call was resolved), the severity, the reason, and the final recording outcome. Because the audit write runs after the recording attempt, it records the true final state. The distress-alert rows themselves live in the tenant schema and follow the tenant’s standard retention windows — see Retention windows and deletion. When a row reaches the end of its window, the deletion is itself auditable per the tenant retention configuration. Treat the ledger as the canonical incident record: supervisors clear alerts from their view, but the row and its audit entry remain the compliance answer to “what happened on this call.”