> ## 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 assist copilot for text and chat threads

> When a live inbox thread turns risky, the supervisor assist copilot streams one recommended move: whisper-coach the agent, hand over a ready reply, take the thread over, or keep watching. The text-thread sibling of voice whisper coaching, plus the dialer's compliance variant.

# Supervisor assist copilot for text and chat threads

The operator-facing AI co-pilot drafts replies for the agent assigned to a thread. The supervisor assist copilot sits one seat up: it reads the same live thread from the oversight side and recommends a single move, framed for supervision. Coach the agent privately, hand them a concrete reply, take the conversation over, or keep watching. This page walks the flag, suggestion, and whisper-or-escalate loop for SMS, WhatsApp, email, social, and web chat threads, and closes with the dialer variant that adds compliance prompts on outbound calls.

**Base path:** `/api/v1/inbox`

**Base surface:** the co-pilot panel on a live thread in the unified inbox (elevated roles only), or any SSE client against the stream endpoint.

***

## Two copilots in the inbox, and when each fires

| | Operator AI co-pilot | Supervisor assist copilot |
| - | - | - |
| **Who sees it** | The agent assigned to the thread | Owners, admins, and supervisors watching their workspace's queues |
| **When it fires** | On every new inbound message in an open thread | On a debounced read of the live thread as it develops; most threads rest on "keep watching" |
| **What it outputs** | A drafted reply the agent accepts, edits, or discards | One oversight card: intervene, escalate, offer, or monitor |
| **Who acts on it** | The assigned agent | You: whisper, hand over a reply, or take the thread over |
| **Controls** | Inbox → Settings → AI Deflection (`inbox_copilot`) | Role-gated; no separate workspace toggle |

The operator co-pilot fires per message and is covered in [Inbox AI co-pilot](https://docs.orbit.devotel.io/guides/inbox-ai-copilot.md). The supervisor copilot fires on the thread's trajectory instead: a churn or cancellation threat, a compliance exposure, abuse, a customer going cold after a stalled answer, an agent visibly out of their depth. On an ordinary healthy thread it stays on `monitor`, so a card that is not "keep watching" means something genuinely moved.

The voice equivalent, whisper coaching on live calls with the supervisor whisper-vs-barge lane, is covered in [real-time agent-assist whisper coaching](https://docs.orbit.devotel.io/guides/agent-assist-whisper-coaching.md) and [supervisor live monitoring for voice](https://docs.orbit.devotel.io/guides/supervisor-live-monitoring-voice.md). This page is its text-thread sibling.

## Enablement, roles, and scope

Supervisor assist has no separate kill switch; access is role-gated.

* The panel and the stream require an elevated role, owner, admin, superAdmin, or supervisor, plus an inbox read or write scope on API keys.
* Every request is scoped to your workspace. A conversation id from another workspace returns a plain `404` before the stream opens, and missing or insufficient credentials return `401`/`403` as JSON, never as a half-opened stream.
* The panel hides itself on finished threads (closed, resolved, archived). If the thread is already closed when a stream connects, you get `event: status` with `terminal: true` followed by `event: end { "reason": "terminal" }`.

The workspace settings keys you may already know govern the operator surface, not this one: **AI co-pilot enabled** and **auto-approve confidence threshold** (`inbox_copilot`) shape draft generation for assigned agents, as described in [Inbox AI co-pilot](https://docs.orbit.devotel.io/guides/inbox-ai-copilot.md#configure-in-the-dashboard). The supervisor loop reads the live thread independently of both values, so tightening the operator threshold does not change when supervisor cards fire, and the co-pilot kill switch does not blind your oversight lane.

## The rescue loop: read the card, whisper or take over

Open a live thread and the panel renders the freshest card. Each card carries:

* `recommended_action` — `intervene`, `escalate`, `offer`, or `monitor`.
* `headline` — a terse imperative summarising the ask.
* `rationale` — one short paragraph grounded in what the customer and agent actually wrote.
* `suggested_message` — ready-to-relay text: a private coaching whisper on `intervene`, a ready reply on `offer`; omitted on `monitor` and `escalate`.
* `urgency` — low, medium, or high; the panel's colour cue.
* `sentiment_score` — a rolling customer-sentiment estimate on \[-1, +1].

Work the card through one of four paths:

1. **Whisper the agent (`intervene`).** The suggested tip goes to the assigned agent as a private coaching note; the customer never sees it. Use it when the agent is one fact or one tone shift away from recovering the thread.
2. **Hand over a reply (`offer`).** The suggested reply is inserted into the thread's composer through the same insert path as AI-draft suggestions, so it is reviewed and sent by a person. Nothing reaches the customer without a click.
3. **Take over (`escalate`).** The panel points you at the takeover surface. The handoff itself, including what the customer sees during the transition, is covered in [supervisor takeover and warm handoff](https://docs.orbit.devotel.io/guides/supervisor-takeover-warm-handoff.md). Reserve it for genuine risk: churn threats, compliance breaches, abuse, or an agent clearly out of their depth.
4. **Keep watching (`monitor`).** The calibrated default. No action needed.

Feeding the outcome back needs no extra step: the copilot re-reads the thread as new messages land, so a whisper that produces a better agent reply shows up in the next card's rationale and sentiment. Where a rescued thread needs structured follow-up, the post-hoc coaching queue and [QM coaching](https://docs.orbit.devotel.io/guides/inbox-coaching.md) pick up where the live loop leaves off.

### The card on the wire

`GET /api/v1/inbox/conversations/{conversationId}/supervisor-assist/stream`

```bash cURL theme={null}
curl -N "https://orbit.devotel.io/api/v1/inbox/conversations/conv_8f2k/supervisor-assist/stream" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream"
```

```typescript Node theme={null}
const es = new EventSource(
  "https://orbit.devotel.io/api/v1/inbox/conversations/conv_8f2k/supervisor-assist/stream",
  { headers: { "X-API-Key": "dv_live_sk_your_key_here" } },
);
es.addEventListener("assist", (ev) => renderCard(JSON.parse(ev.data)));
es.addEventListener("end", (ev) => {
  if (JSON.parse(ev.data).reason === "max-duration") es.close(); // reconnect to resume
});
```

The stream opens with `event: connected` (`{ "conversationId", "status" }`), then `event: status` (`{ "status", "terminal" }`). Cards arrive as `event: assist`, a `: ping` keepalive lands every 15 seconds, and `event: end` closes the session with `reason: "terminal"` on a closed thread or `reason: "max-duration"` at the 30-minute cap; reconnect with the same URL to continue.

One `event: assist` frame's `data`:

```json 200 theme={null}
{
  "id": 12,
  "generated_at": "2026-08-28T09:41:22Z",
  "model": "claude-sonnet-4-6",
  "recommended_action": "offer",
  "headline": "Offer the 30-day price lock",
  "rationale": "The customer has asked twice whether their current rate survives the plan change; a concrete lock answer removes the last blocker before they upgrade.",
  "suggested_message": "You can keep your current rate for 30 days after the plan change. I can apply the lock today if you confirm.",
  "urgency": "medium",
  "sentiment_score": -0.2
}
```

Cards are deliberately debounced: the loop waits for at least two new thread turns and at least 12 seconds between model calls, and reads only the trailing \~6,000 characters, so a long thread costs the same per card as a short one. The most recent 30 turns seed the connection, so the first card already has context.

## The dialer variant: compliance prompts on outbound calls

The same assist family covers outbound dialer calls, with two additions built for outbound risk: objection-handling rebuttals when a contact stalls or pushes back, and compliance prompts that nudge the agent to deliver the required opening disclosure. The moment a contact asks to be removed, the copilot drops the pitch and switches to a compliant acknowledgement. Outbound calls are recognised automatically from the call's direction and campaign, so there is nothing extra to configure.

* Configure the disclosure content itself in [AI disclosure setup](https://docs.orbit.devotel.io/guides/ai-disclosure-setup.md).
* Watch disclosure and do-not-call handling across the floor in [live compliance monitoring](https://docs.orbit.devotel.io/guides/live-compliance-monitoring.md).

## Tuning and telemetry

* **Cadence is fixed, as on voice.** Two new turns, a 12-second minimum gap, and the trailing 6,000 characters. There is no tenant-tunable threshold on the supervisor side; if your floor wants a tighter cue, render or discard cards client-side.
* **The `inbox_copilot` threshold is a different dial.** `auto_approve_confidence_threshold` (default 0.9) marks operator drafts as eligible for one-click approval in the composer. It never sends anything on its own, and it does not gate supervisor cards.
* **Reading usage.** Team-level handling reads live in [inbox team performance](https://docs.orbit.devotel.io/guides/inbox-team-performance.md). For the operator co-pilot, the accept/edit/discard rollups are described in [Inbox AI co-pilot](https://docs.orbit.devotel.io/guides/inbox-ai-copilot.md#telemetry-per-day-auto-approve-rate-visibility).
* **The contract is advisory.** Every suggestion on both surfaces carries `require_human_review: true`. A person clicks send on every customer-visible message; the copilot recommends, it never dispatches.

## Failure modes

* **No cards on a live thread** — either the thread is healthy and resting on `monitor`, or the model layer is degraded while the stream stays open. A stream that holds `connected` and keeps pinging for over a minute with no `assist` frames is the degraded-model signature; the panel keeps showing the last card it received.
* **Thread already closed at connect** — `event: status` with `terminal: true`, then `event: end { "reason": "terminal" }`. Reconnecting is pointless; the coaching queue covers retrospection.
* **The 30-minute cap elapses** — `event: end { "reason": "max-duration" }`; reconnect with the same URL and continue watching.
* **401 / 403 / 404 before the stream** — a role, scope, or workspace mismatch. Errors arrive as clean JSON because authorization completes before the SSE handshake opens.

## Related

* [Inbox AI co-pilot](https://docs.orbit.devotel.io/guides/inbox-ai-copilot.md) — the operator-facing drafting drawer, kill switch, and thresholds
* [Real-time agent-assist whisper coaching](https://docs.orbit.devotel.io/guides/agent-assist-whisper-coaching.md) — the voice sibling of this loop
* [Supervisor live monitoring for voice calls](https://docs.orbit.devotel.io/guides/supervisor-live-monitoring-voice.md) — listen, whisper, and barge on live calls
* [Supervisor takeover and warm handoff](https://docs.orbit.devotel.io/guides/supervisor-takeover-warm-handoff.md) — the takeover path an `escalate` card points you to
* [Supervisor live monitoring for digital queues](https://docs.orbit.devotel.io/guides/supervisor-live-monitoring-digital.md) — the digital floor view this copilot sits beside
* [AI disclosure setup](https://docs.orbit.devotel.io/guides/ai-disclosure-setup.md) and [live compliance monitoring](https://docs.orbit.devotel.io/guides/live-compliance-monitoring.md) — the dialer compliance pair
* [Inbox team performance](https://docs.orbit.devotel.io/guides/inbox-team-performance.md) — reading handling after the rescue


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.