Human-in-the-loop oversight

An AI agent handles most conversations end to end, but you stay in control of the ones that matter. From a live conversation you can do three things without disconnecting the customer:

Whisper — send the agent a private instruction it reads on its next turn.
Approve a high-risk action — a tool you marked as sensitive pauses for your sign-off before it runs.
Take over — pause the AI and let a human handle the conversation, then hand control back.

All three work on both channels the agent runs on: voice calls and chat conversations (web chat, SMS, WhatsApp, and the other messaging channels).

Prerequisites

The conversation must be live. Whisper and take-over apply to an agent conversation that is active, open, or escalated; a closed conversation returns 404.
These are supervisor actions. Sending a whisper is available to the owner, admin, and supervisor roles; approving or rejecting a tool call is available to owner and admin.
Authenticate every request with an API key (X-API-Key: dv_live_sk_...) or a dashboard session, exactly as with the rest of the API.

Whisper: guide the agent without taking over

A whisper is a one-way note from you to the agent. The agent reads it at the start of its next turn and factors it into that reply — you are steering the model, not messaging the customer. The customer never sees the note. Send a note:

curl -X POST https://api.orbit.devotel.io/api/v1/agents/conversations/:conversationId/supervisor-notes \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "note": "Offer the annual plan discount before they ask to cancel." }'

A note is 1–1000 characters. An empty note or one over the limit returns 400; a conversation that is not live returns 404. On success you get 201 with the created note id:

{ "id": "supnote_...", "conversation_id": "conv_..." }

The agent applies the note on its next turn — so whisper while the conversation is still going. If the conversation ends before the agent takes another turn, the note is never applied and stays marked unread in the history. Read the recent notes for a conversation (newest first, last 20) to build an oversight history panel:

curl https://api.orbit.devotel.io/api/v1/agents/conversations/:conversationId/supervisor-notes \
  -H "X-API-Key: dv_live_sk_..."

Each note carries a consumed_at timestamp — null means the agent has not read it yet, a timestamp means it was picked up on the turn at that time.

Approve a high-risk action

Mark any tool as sensitive by setting its confirmation to "always". When the agent decides to call that tool, the call does not run: the turn pauses, the agent receives a blocked result instead of the tool output, and a pending approval is queued for a human to decide. Use this for irreversible or costly actions — issuing a refund, cancelling an account, sending a contract. Review the queue:

curl "https://api.orbit.devotel.io/api/v1/agents/tool-approvals?status=pending&limit=50" \
  -H "X-API-Key: dv_live_sk_..."

Each row shows what the agent wanted to do — tool_id, the tool_args it proposed, the conversation_id and agent_id, when it was requested_at, and a cost_estimate when the tool priced the call in advance. Filter by status (pending, approved, or rejected). Approve it to let the action proceed. A reason is optional on approve:

curl -X POST https://api.orbit.devotel.io/api/v1/agents/tool-approvals/:id/approve \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Verified the customer on the call." }'

{ "approval_id": "tapprv_...", "status": "approved", "resumed": true, "warning": null }

Approving re-queues the deferred turn so the agent resumes and can complete the action. resumed: true confirms the resume job was accepted. If the resume queue is briefly unavailable, your decision is still saved (resumed: false with a warning string) and the platform retries — the approval record is the source of truth, so no decision is ever lost. Reject it to block the action. A reason is required on reject so the decision is documented:

curl -X POST https://api.orbit.devotel.io/api/v1/agents/tool-approvals/:id/reject \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Refund exceeds the amount on the order." }'

{ "approval_id": "tapprv_...", "status": "rejected" }

Common responses:

Status	Meaning
`404`	No approval with that id in your organization.
`409`	The approval was already approved or rejected — no change is made (treat as “already decided”, not a retryable error).
`422`	You called reject without a `reason`.

Every approve and reject writes an audit record, so you keep a reviewable trail of who decided what and why.

Take over: pause the AI and step in

When a conversation needs a person, pause the agent and take the wheel. The customer stays on the same call or thread — only who is answering changes.

Chat

Hand the conversation to a human, which pauses the agent so it stops replying:

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/:id/handoff \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer asked for a manager." }'

Check who is currently answering — the agent-runtime reads this before every turn, and you can render a “human is handling this” banner from it:

curl https://api.orbit.devotel.io/api/v1/conversations/:id/agent/active \
  -H "X-API-Key: dv_live_sk_..."

{ "agent_active": false, "agent_id": "agent_..." }

agent_active: false means a human has the conversation and the AI will not reply. When you are done, hand control back so the agent processes the next inbound message again:

curl -X POST https://api.orbit.devotel.io/api/v1/conversations/:id/agent/resume \
  -H "X-API-Key: dv_live_sk_..."

Voice

On a live call, pause the AI mid-conversation so a supervisor or human agent can take over the call leg:

curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls/:id/ai-pause \
  -H "X-API-Key: dv_live_sk_..."

The AI stops speaking on that call while a human continues it.

Roles at a glance

Action	Roles
Send / read whisper notes	`owner`, `admin`, `supervisor`
Approve / reject a tool call	`owner`, `admin`
Hand off, resume, or pause the AI	`owner`, `admin`

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

Human-in-the-loop oversight

Human-in-the-loop oversight

Prerequisites

Whisper: guide the agent without taking over

Approve a high-risk action

Take over: pause the AI and step in

Chat

Voice

Roles at a glance

See also

​Human-in-the-loop oversight

​Prerequisites

​Whisper: guide the agent without taking over

​Approve a high-risk action

​Take over: pause the AI and step in

​Chat

​Voice

​Roles at a glance

​See also

Human-in-the-loop oversight

Prerequisites

Whisper: guide the agent without taking over

Approve a high-risk action

Take over: pause the AI and step in

Chat

Voice

Roles at a glance

See also