​

Supervisor warm takeover and coach mode

​

Takeover vs the monitoring verbs

• A monitoring whisper is a moment-to-moment tool on a call you happen to be viewing; stopping it is informal and it leaves no dedicated takeover record.
• Coach mode creates a takeover row in whisper_only state, audits supervisor.takeover.whisper_initiated, keeps the session visible in the takeovers panel, and ends with an explicit cancel that also drops your leg. Choose it when the coaching session itself matters: training, a struggling agent you want to support for several minutes, or a compliance posture that needs “who coached whom and for how long” answerable.

​

Console walkthrough

1. You need a connected softphone session. If your supervisor leg is not connected, the console prompts you to connect first; the takeover redirects your existing leg into the call.
2. Select Take over call on the live call. The dialog shows the agent being replaced.
3. Pick a reason: Manual, Agent struggling, Customer escalation, Low quality score, or Training / coaching. The reason is stored on the takeover row and included in webhooks.
4. Pick the whisper grace: Immediate (0 s), 5 s, 10 s, 15 s, or 30 s. During the grace you are bridged in whisper to coach the agent while the agent finishes their sentence; when the grace elapses the handoff runs and the agent leg drops. 0 skips the grace and hands off immediately. The default is 5 s.
5. Confirm. The dialog notes that the action is audit-logged and that you remain responsible for local call-recording and notification laws.

​

API walkthrough

​

Initiate a takeover

curl -X POST https://orbit.devotel.io/api/v1/voice/supervisor/takeovers \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "call_8f3k2",
    "supervisor_call_sid": "sup_call_9",
    "agent_call_sid": "agent_call_4",
    "agent_being_replaced": "user_7qAgent",
    "reason": "customer_escalation",
    "whisper_grace_seconds": 5,
    "conversation_id": "conv_2210"
  }'

​

Advance or cancel

curl -X PATCH https://orbit.devotel.io/api/v1/voice/supervisor/takeovers/takeover_1a2b \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"state": "completed", "notes": "Closed the refund with a 12-month credit."}'

​

List and read back

curl "https://orbit.devotel.io/api/v1/voice/supervisor/takeovers?call_id=call_8f3k2&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

curl https://orbit.devotel.io/api/v1/voice/supervisor/takeovers/takeover_1a2b \
  -H "X-API-Key: dv_live_sk_your_key_here"

​

The warm-handoff state machine

• requested → whisper_phase, handoff_in_progress, or taken_over
• whisper_phase → handoff_in_progress or taken_over
• handoff_in_progress → taken_over
• taken_over → completed

• Whisper-grace semantics: during whisper_phase you hear both parties and speak to the agent only; the agent can use the grace to finish a thought or hand over cleanly. When the deadline elapses the scheduler advances the row, captures the conversation context (bounded to a few seconds; on timeout the handoff proceeds without it), and fires the leg swap.
• Cancellation: PATCH … "state": "cancelled" aborts from any non-terminal state. There is no automatic grace-to-handoff for coach mode rows (below); those end only by cancellation.
• Failure: if the leg swap fails, the row is set to cancelled and a supervisor.takeover_failed webhook fires; you can initiate a fresh takeover on the same call.
• One open takeover per call: a second initiate against a call with a non-terminal row returns 409 naming the open row.
• Webhooks and events: the lifecycle emits supervisor.takeover_requested, supervisor.takeover_completed, supervisor.takeover_failed, and supervisor.takeover_cancelled; the console refreshes live on the supervisor event stream, so the panel reflects scheduler-driven advances without polling.

​

Coach mode (whisper_mode)

curl -X POST https://orbit.devotel.io/api/v1/voice/supervisor/takeovers \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "call_8f3k2",
    "supervisor_call_sid": "sup_call_9",
    "agent_call_sid": "agent_call_4",
    "agent_being_replaced": "user_7qAgent",
    "reason": "training",
    "whisper_mode": true
  }'

• Audio-only coaching: your audio routes to the agent leg only. The caller never hears you.
• agent_call_sid is required: the coach routing needs the agent leg; without it the request returns 422.
• No LLM context capture: the conversation summary exists to brief a supervisor who is about to replace the agent. In coach mode the agent keeps driving, so no summary is generated.
• No agent-leg drop, no grace deadline: whisper_grace_seconds is ignored and nothing schedules a handoff. The agent stays the primary speaker for the whole session.
• Terminal state whisper_only: the row lands in whisper_only, which the handoff scheduler never touches. The only exit is PATCH … "state": "cancelled", which also drops your coaching leg. The panel shows these rows as “Coach (whisper)”.
• Distinct audit action: supervisor.takeover.whisper_initiated instead of supervisor.takeover.initiated, so compliance reporting can separate “supervisor coached” (no caller-audible change) from “supervisor replaced the agent” (new voice on the line). State advances and cancels audit as supervisor.takeover.updated.

​

Who may initiate

• Owner and admin (and platform staff) initiate takeovers on any queue in the workspace.
• Supervisor role is queue-scoped: a supervisor may initiate only on calls that landed in a queue they are explicitly assigned to supervise. Assignments are managed by an owner or admin in the team management UI. A supervisor with no queue assignments can take over no calls (fail-closed), and the 403 response does not reveal which queues exist or who supervises them.
• Calls without a queue (direct-dial, non-ACD) are not queue-gated for supervisors.
• This is the same role model the monitoring verbs use: if a supervisor can see a queue on the wallboard, they can take over its calls; advancing or cancelling a specific takeover is additionally limited to the supervisor who initiated it.

​

AI-agent conversations

​

Worked example: an escalating billing call

1. A billing call turns hostile on the wallboard. You open Voice → Monitoring and Listen to confirm the agent is losing the thread.
2. On the call row, select Take over call, reason Customer escalation, whisper grace 5 s, confirm. The panel shows the row in whisper_phase.
3. For five seconds you hear both parties and whisper to the agent: “I am taking this one, transfer the refund authority note.” The caller hears only the agent.
4. At the deadline the row advances handoff_in_progress → taken_over; the agent leg drops and the caller continues with you, no re-dial. You open with the preserved summary the console captured.
5. After the call, open the row in the takeovers panel, advance it to completed with a coaching note (“De-escalated with a 12-month credit; revisit the refund-authority script”), or PATCH state: "completed" with notes via the API. The detail drawer reads back the final state, timestamps, and your note.

​

Failure modes