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

# Auto-draft help articles from resolved conversations

> Close the loop between support and your knowledge base — opt in, cap drafts per run, mine resolved conversations on demand, and publish AI-mined drafts through human review.

# Auto-draft help articles from resolved conversations

KB auto-draft closes the loop between your support traffic and your knowledge
base. Orbit already mines every resolved conversation into a ranked list of
recurring contact reasons (the automation-opportunities surface on the
Insights dashboards). For the reasons flagged as "best deflected by a help
article," auto-draft takes the next step: it files a **draft article** —
built from the real customer excerpts — into a review queue, so a subject-owner
turns the mined material into a finished, approved article instead of
authoring one from a blank page.

This guide covers the dashboard surface — **Insights → Auto-drafted
knowledge** (`/insights/kb-auto-draft`) — plus the API endpoints behind it,
and ends with a worked resolved-conversation → draft → publish cycle.

## What auto-draft does

Each mining run scans your resolved conversations over a rolling 30-day
window and ranks the recurring reasons customers contact you about. For each
high-volume reason that is best covered by a help article, the run:

1. Collects up to five recent, distinct customer excerpts for that reason.
2. Drafts an article body from those excerpts plus a reviewer checklist —
   the draft is extractive (real customer questions), never generative, so it
   cannot invent a resolution that didn't happen.
3. Files the draft into a dedicated **Auto-Mined Drafts (Pending Review)**
   knowledge base, created automatically on your first run.

Nothing drafts without qualification. A reason only becomes a draft when it
clears three bars: the ranking analysis flags it as best deflected by
a help article, at least two distinct real excerpts exist for it, and no
draft for the same reason already exists in the review queue (any status) —
so a daily sweep never piles up duplicates of the same topic.

The drafts queue is deliberately separated from your live knowledge bases. A
draft can never ground an AI agent's answer until a human approves it — the
pool knowledge base enforces publish approval on every document regardless
of your workspace's default upload posture.

## Enable the module

Auto-draft is **opt-in** per workspace — Orbit never mines your conversations
into a shared knowledge base without your say.

In the dashboard, open **Insights → Auto-drafted knowledge**, flip
**Automatically draft knowledge articles** on, and save. That is the whole
setup: the scheduled sweep now includes your workspace on its daily pass.

Via the API:

```bash theme={null}
curl -X PUT https://api.orbit.devotel.io/api/v1/insights/kb-auto-draft/config \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "max_drafts_per_run": 3 }'
```

Both fields are optional on each `PUT` — send only what you want to change.
Read back the current values with
`GET /insights/kb-auto-draft/config`.

**Access.** The config endpoints accept a workspace session token (owner,
admin, developer) or an API key with the `insights:read` scope. Triggering a
run (`POST .../run`, below) additionally requires an owner, admin, or
developer role, because it writes a new knowledge document.

## Thresholds and filters

Two tenant-controlled settings and two fixed qualification bars decide what
lands in your queue.

**Your controls:**

* **`enabled`** — the on/off switch. When off, the scheduled sweep skips your
  workspace entirely; a manual run (below) still works, because an explicit
  "run now" is itself the consent the gate exists for.
* **`max_drafts_per_run`** — between 1 and 10, default 3. Caps how many new
  drafts one run may file, so a reviewer's queue is never flooded by a single
  sweep. Runs file the highest-ranked candidates first.

**The fixed bars (not operator-tunable):**

* Only reasons the mining analysis already ranks as
  "best deflected by a help article" are drafted —
  dialer-script or workflow-shaped opportunities never become articles.
* A reason needs at least two distinct real excerpts in the 30-day window;
  below that, there isn't enough signal for a useful draft and it is skipped
  until more conversations resolve.
* Per-topic dedup: once a reason has a draft in the queue — pending,
  approved, or rejected — later runs skip it. To re-mine a rejected reason,
  delete the rejected document from the pool knowledge base.

## The review queue

Every draft lands in **Auto-Mined Drafts (Pending Review)** — a knowledge
base Orbit finds or creates on your first run — visible under
**Agents → Knowledge base** in the dashboard. It behaves like any other
knowledge base, with one difference: publish approval is mandatory, so
documents sit in a **pending** state until a human acts.

Each pending draft carries three parts:

* **Why customers are asking** — conversation volume for the reason over the
  window, the dominant channel it arrives on, and the current self-service
  deflection rate, so you know how exposed agents are today.
* **What customers are saying** — up to five verbatim customer excerpts, the
  raw material the article should answer.
* **Reviewer checklist** — replace the excerpts with a clear explanation, add
  the actual resolution steps (the draft deliberately contains none), then
  approve to publish.

Draft versus published is a hard line. A pending draft is invisible to every
AI agent attached to any knowledge base: its chunks are not embedded and not
retrievable. The moderation queue is the only path to live, and it is
human-in-the-loop by construction — auto-draft writes, people decide.

## Publishing to the knowledge base

Review a draft in **Agents → Knowledge base → Auto-Mined Drafts (Pending
Review)**:

1. Open the pending document, rewrite the body into a real article — resolve
   what the excerpts ask, keep the checklist honest.
2. **Approve** it. Approval embeds its chunks, making the article retrievable
   by your AI agents in the same way as any approved upload.
3. Or **reject** it when the mined reason is noise. The rejection still counts
   for per-topic dedup, so the sweep stops re-drafting that reason.

The same lifecycle is available over the API —
`POST /knowledge-bases/:id/documents/:docId/approve` and
`POST /knowledge-bases/:id/documents/:docId/reject` — so a publishing bot or
an internal review tool can drive the queue headlessly. See the full
lifecycle in [Build and Maintain an AI Knowledge Base](/guides/knowledge-base-lifecycle).

If you prefer to move approved content into your main knowledge base, copy
the approved body into a document in that base and delete the draft — the
pool base is a staging area, not a permanent home.

## Worked example — resolved conversation to published article

A workplace-benefits operator turns the module on with the defaults
(`enabled: true`, `max_drafts_per_run: 3`) on a Monday.

**Tuesday's sweep** mines the last 30 days of resolved conversations. The
topic-intelligence pass has been flagging `open_enrollment_dates` — 61
resolved conversations, mostly over chat, with a 12% self-service deflection
rate — as the reason best deflected by a help article. The run pulls five
recent excerpts ("when does open enrollment close?", "can I change my plan
after enrollment ends?", …) and files a draft titled *Open enrollment dates —
draft help article (auto-mined)* into the pending queue. Two lower-ranked
reasons also draft; the queue cap of 3 stops there.

**The reviewer** opens **Agents → Knowledge base → Auto-Mined Drafts** before
the weekly content meeting. For the open-enrollment draft she replaces the
excerpts with two paragraphs ("Open enrollment runs Nov 3–21. Plan changes
are locked after Nov 21 except for qualifying life events."), links the HR
portal, and approves. The article's chunks embed within the minute; attached
agents now answer enrollment-date questions from it instead of escalating.

**The next sweep** skips `open_enrollment_dates` — an approved draft exists —
and moves on to the next-ranked undrafted reason. Over a month, the
deflection-rate column on the Insights dashboards shows the published
articles absorbing exactly the traffic they were drafted for.

**Manual run, anytime.** The same page's **Run now** button (or
`POST /insights/kb-auto-draft/run`) executes a mining pass on the spot — it
works even while the scheduled sweep is off, and returns
`{ drafted, candidates }` so an integration can tell "nothing qualified" from
"drafts filed."

## See also

* [Build and Maintain an AI Knowledge Base](/guides/knowledge-base-lifecycle) — the full document lifecycle, retrieval tuning, and gap/staleness reports
* [Insights dashboards](/guides/insights-dashboards) — the mining analytics that rank which reasons get drafted
* [AI agent rollout pipeline](/guides/ai-agent-rollout-pipeline) — attach the approved knowledge base to an agent