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

# Voice coaching plans: author, track, and close with measured impact

> Author multi-week coaching plans for an agent, track improvement sessions against a goal, close the plan with an outcome, and read the before/after KPI report that measures what actually moved.

# Voice coaching plans: author, track, and close with measured impact

A coaching plan is a multi-week improvement program for one agent: a goal, a target date, coaching sessions linked to it, a close-out judgement, and a measured before/after read on the agent's metrics. The workspace lives at **Voice → Coaching Plans**. Individual coaching notes on a call's detail page continue to capture the moment — the plan rolls those sessions into one tracked cycle with a verdict on whether the agent's numbers moved.

## 1. The plan lifecycle

Every plan moves through the same arc:

1. **Author** — a supervisor (or an auto-coaching trigger) opens the plan against an agent with a goal statement and an optional target date. The plan starts as `active`.
2. **Mid-period** — the plan is editable while active. Link per-call coaching notes to it, revise the goal or target date, and check in-flight progress on the metrics at any time.
3. **Close with outcome** — the plan ends with a terminal status (`completed` or `cancelled`) and your outcome judgement (`met`, `partial`, or `missed`). The close is permanent: a closed plan cannot be edited or re-closed to a different status.

Plans appear in your workspace two ways — supervisor-authored, or auto-assigned when a QA score, detractor CSAT response, or sustained adherence breach crosses its threshold. Auto-assigned plans carry a source tag on the goal (for example, `qa_score` or `csat`) and a `system` owner, and they behave exactly like supervisor-authored plans once open. See the auto-coaching thresholds in [Build a contact-center QA program](/guides/quality-management-program).

## 2. Author a plan

Open **Voice → Coaching Plans** and click **New plan**, or post to the API:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/coaching-plans \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_user_id": "user_agent_12",
    "goal": "Cut average handle time by 20% before quarter close",
    "due_at": "2026-10-15T00:00:00Z"
  }'
```

Three fields define the plan:

* **`agent_user_id`** — the agent the plan addresses (required).
* **`goal`** — the improvement statement, up to 2,000 characters. Write
  it against the metric the effectiveness report measures (AHT,
  first-contact resolution, or CSAT where available) so the close-out is
  decidable on data, not impressions.
* **`due_at`** — optional target date (ISO 8601). A short dated window
  keeps the cadence of coaching sessions bounded; omit it for an
  open-ended plan you close manually once the goal lands.

The response returns the plan (`201`) as `active` with you as the owner. During the mid-period you can revise the goal, target date, or addressed agent — `PUT /voice/coaching-plans/{id}` accepts any subset of those fields. Editing a closed plan returns `409 PLAN_CLOSED`.

<Note>
  Screenshot placeholder — the **New plan** composer at **Voice → Coaching Plans**, showing the agent selector, goal field, and target-date input. Capture against a tenant with at least one active plan so the list below the composer is visible.
</Note>

## 3. Track the mid-period

The workspace lists active plans first, then closed ones, ordered by target date. Filter by agent, owner, or status from the dashboard, or over the API:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/coaching-plans?status=active&agent_user_id=user_agent_12" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

Link the coaching sessions that move the goal: the coaching-note composer on a call's detail page attaches the note to an open plan, so every session accrues to the same cycle. `GET /voice/coaching-plans/{id}` reads one plan with its current status and outcome fields.

## 4. Close with an outcome

When the cycle ends, close the plan from the **Close** dialog in the workspace, or post:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/coaching-plans/cplan_abc123/close \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "outcome": "met",
    "outcome_notes": "AHT fell from 340s to 268s. Goal was a 20% cut."
  }'
```

* **`status`** — `completed` (default) or `cancelled`.
* **`outcome`** — `met`, `partial`, or `missed`. Required at close; it
  records your judgement, and it stays a judgement by design.
* **`outcome_notes`** — optional narrative, up to 2,000 characters.

Closing the same plan twice in the same terminal state returns `200` instead of an error, so an accidental double-click is safe. Trying to re-close it differently returns `409 PLAN_ALREADY_CLOSED`.

## 5. Read the before/after KPI report

Your outcome call is subjective. The effectiveness report is the objective complement — it compares the agent's real metrics from a window before the plan against a window after it:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/coaching-plans/cplan_abc123/effectiveness?window_days=14" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

Each KPI returns the before value, the after value, the delta, the percent change, and a direction (`improved`, `regressed`, `flat`, or `insufficient_data`):

* **Average handle time (`aht_seconds`)** — talk-only duration per completed call. Lower is better.
* **First-contact resolution (`fcr_pct`)** — share of completed calls where the same caller did not call back within the follow-up window (default 24 hours). Higher is better.
* **CSAT (`avg_csat`)** — mean 1–5 score from post-call surveys. Higher is better.

The two windows are symmetric — `window_days` long each (default 14, up to 90):

* The **before** window is the span immediately preceding the plan's creation, so coaching-in-progress calls never pollute the baseline.
* The **after** window anchors on the close date for a closed plan. For a still-active plan it anchors on creation and reports in-flight progress, flagged as `in_progress` in the response.

When a KPI has no data in either window, the report says `insufficient_data` rather than a misleading zero delta. Check the report before you close: a plan you are tempted to extend may already show the improvement, and a plan you marked `met` that still shows regressed handle time deserves a second look.

<Note>
  Screenshot placeholder — the **Coaching effectiveness** panel on a plan in **Voice → Coaching Plans**, showing the before/after values and direction for AHT, FCR, and CSAT. Use a closed plan so the report reads as a post-completion measurement.
</Note>

The same report powers the **Coaching effectiveness** panel in the dashboard, so supervisors who never touch the API read the same numbers.

## Templates, or an ad-hoc plan?

Every plan has the same shape — an agent, a goal, a target date — but the phrasing of the goal varies. The curated template library at **Voice → Coaching Templates** holds vetted coaching phrases that supervisors reuse across shifts, so floor coaching stays on-brand. Reach for it when the gap recurs ("de-escalate angry caller", "ask a discovery question"); write an ad-hoc goal statement when the plan targets a specific metric move. Templates standardize the wording; they never substitute for the plan itself.

## Pair plans with QA and coaching notes

The close-out works best when the cycle runs on evidence:

* **QA scorecards** — a low evaluation score can auto-assign the plan in the first place, and re-scoring the agent during the cycle tells you whether the behaviors changed.
* **Coaching notes** — link every session note to the plan so the cycle reads as one program, not scattered comments.
* **Effectiveness report** — let AHT / FCR / CSAT arbitrate the outcome at close instead of impressions.

## Who sees and edits plans

Owners, admins, and supervisors can create, edit, close, and read any plan. An agent sees only the plans addressed to them — and their own effectiveness report. Attempting to read another agent's plan returns `403`.

## See also

* [Build a contact-center QA program](/guides/quality-management-program) — the auto-coaching thresholds that assign plans without a supervisor
* [Supervisor coaching: plans, templates, and effectiveness reporting](/guides/supervisor-coaching) — the template library and the full coaching workspace in one guide
* [Agent assist: whisper coaching](/guides/agent-assist-whisper-coaching) — in-call guidance the template library also serves
* [Error codes](/api-reference/error-codes) — the `409` state-conflict and `403` role shapes this surface returns