Skip to main content

​
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:
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. 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