> ## 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.

# Supervisor live monitoring for digital conversations: watch, whisper, barge

> Give your supervisors the same listen / whisper / barge control over live chat, SMS, WhatsApp, web-chat and email threads that contact-centre supervisors have over phone calls — in real time, not just after the fact.

# Live monitoring for digital conversations

Quality scoring tells you how an agent handled a conversation *after* it ended. Live monitoring tells you what's happening *right now* — and a supervisor can step in while the customer is still waiting. On digital channels (web chat, SMS, WhatsApp, social, email) there are four actions:

* **Watch** — silently follow the thread. Supervisors see the transcript live without the customer or the agent being told.
* **Whisper** — send a private coaching tip to the handling agent. The tip lands as an internal note in the agent's open thread; the customer never sees it.
* **Barge** — take over the conversation. From this point on the supervisor's replies are what the customer sees, and the thread is reassigned to the supervisor.
* **Unwatch** — stop a watch session (available to the supervisor who started it).

Every action is visible on the supervisor wallboard and in the agent's thread as a live badge (watching / coached / seized), so the whole team can see who is overseeing which conversation.

## Watch a conversation

From the dashboard, a supervisor opens any live conversation and chooses **Watch** — or over the API:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_123/monitor/watch \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

The response confirms the session is active and reports the stamped marker:

```json theme={null}
{
  "conversation_id": "conv_123",
  "action": "listen",
  "status": "active",
  "trait": "watching",
  "assigned_to": "agent_user_2",
  "supervised_by": {
    "supervisor_user_id": "sup_user_1",
    "kind": "watching",
    "since": "2026-08-24T14:03:11.000Z"
  }
}
```

Watching is read-only — the supervisor is invisible to the customer and never appears in the transcript. Stop the session with **Unwatch**:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_123/monitor/unwatch \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

A supervisor can only stop their own watch session — one supervisor can't clear a colleague's marker. If the thread was taken over (barged), stopping the watch doesn't hand it back; assign it back to the agent explicitly (see below).

## Whisper a coaching tip

When an agent is mid-conversation and a supervisor can see the right move, they can coach without the customer seeing anything:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_123/monitor/whisper \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Offer the retention credit — it is on their profile."}'
```

The tip arrives in the agent's open thread as an internal note marked **supervisor coaching**, delivered over the same inbox channel the agent already subscribes to — so there is nothing new for the agent to poll. The tip is bounded to 500 characters; an empty tip returns `422 EMPTY_TIP`. Whisper requires an agent to be actually assigned to the conversation (you can't coach nobody) and an open thread (closed/archived threads return `422`).

## Barge in (take over the thread)

When coaching isn't enough, the supervisor takes the thread:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_123/monitor/barge \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

From that moment the conversation is assigned to the supervisor and their replies are the ones the customer sees. Barge is idempotent — a supervisor who already owns the thread gets `already_barged: true` back and nothing re-stamps.

The takeover respects your team's channel concurrency caps: if the supervisor is already at their maximum for that channel (for example `email = 1`), the barge is refused instead of silently overflowing their workload — the same rule a manual reassign would apply.

Handing the thread back is an explicit assign:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/conversations/conv_123/assign \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"assigned_to": "agent_user_2"}'
```

## Who can monitor

Every live-monitoring endpoint requires an elevated role — owner, admin, or supervisor — plus a full agent seat in your workspace. The hard-delete-of-a-conversation gate isn't relaxed here either: a developer or billing member gets `403`.

## Permissions and audit trail

Every watch / whisper / barge / unwatch action is audit-logged with the acting user, the conversation, the action, and the caller IP, so you can answer "who took over that VIP thread?" months later.

## Common failure codes

| Status | Code             | What it means                                                      |
| ------ | ---------------- | ------------------------------------------------------------------ |
| 422    | `ALREADY_CLOSED` | The thread is closed or archived — monitoring needs a live subject |
| 422    | `EMPTY_TIP`      | Whisper came with an empty coaching tip                            |
| 422    | `NO_ASSIGNEE`    | Whisper or barge tried on an unassigned thread                     |
| 403    | —                | Caller is not owner/admin/supervisor                               |
| 404    | `NOT_FOUND`      | The conversation id doesn't exist for this tenant                  |