Skip to main content

​
Close knowledge-base deflection gaps

Every customer question your AI deflection ranker cannot answer — because the knowledge base has no candidate article, or because the best candidate’s confidence falls below the answer threshold — is recorded the moment the miss happens. The Deflection Gaps page turns those misses into a clustered report: “47 contacts asked about refund timing — your KB has no article,” with a suggested topic and the verbatim questions behind each cluster. Open it at Agents → Knowledge base → Gaps (/agents/knowledge-base/gaps). The page exists so KB authors work from a ranked queue of what the AI missed, not from individual escalations. You can also read the same report over the API:
The response is a report { days, total_misses, clusters } where each cluster carries cluster_id, representative_query, miss_count, conversation_count, suggested_topic, and recent examples of the verbatim customer questions.

​
What the deflection-gap list captures

A miss is recorded at the exact moment the ranker fails an incoming question, in one of two shapes:
  1. No candidate — the ranker searched the attached knowledge base and found nothing that could answer the question. The topic is missing entirely.
  2. Below the deflection threshold — a candidate existed, but its match confidence came in under the 0.75 deflection threshold, so the customer was escalated instead of answered. Topic-adjacent material exists, but it does not actually resolve the question.
Both shapes tell you the same thing — write an article here — but the first is a coverage gap and the second is a resolution-quality gap. The page shows the union on purpose: a low-confidence match and a complete absence both end in the same customer experience, an unanswered question. Only genuine attempts count. When deflection never ran on a conversation — no AI key configured, or an empty inbound message — nothing is recorded, so the report is not diluted with unattempted deflections.

​
How clustering works

Misses are grouped by token overlap: each question is tokenized (stopwords and punctuation stripped), and two questions join the same cluster when their token sets overlap at a similarity of 0.4 or higher. Clusters sort by miss count, with the conversation count breaking ties, so the highest-impact gap sits on top. Each cluster row shows:
  • Miss count — how many times this question cluster was missed in the window.
  • Conversation count — how many distinct conversations produced those misses, so you can tell one persistent customer asking ten times apart from ten customers asking once.
  • Suggested topic chip — the highest-frequency meaningful token across the cluster’s questions. It is not the article title; it is the starting hint for the article’s slug. A cluster whose top token is refund is telling you where to file the article, not what to name it.
  • Recent examples — the most recent customer questions, verbatim, so you write to what customers actually ask rather than a paraphrase.
The page header totals the misses for the current window even when the cluster list is sampled short, so the badge number is the true count, not the visible list size. Two controls adjust the report: the look-back window (7 to 90 days, default 30) and the cluster count (top 5 to 50, default 10).

​
Two gap signals, side by side

The parent Knowledge base page already carries an older knowledge-gap report. They answer different questions:
  • The Knowledge base page panel keys on the agent-conversation signal: assistant turns that contained “I don’t have that information”-class phrasing, and conversations escalated to a human citing a knowledge gap. It derives gaps after the fact, from what agents said.
  • The Deflection Gaps page (this guide) keys on the deflection-miss signal: the customer’s question captured synchronously the moment the ranker could not answer it.
The two are siblings, designed to be merged into a single tab later; today they live side by side. Use the deflection-miss list when you want the questions customers brought to the AI; use the older panel when you want the failures your agents admitted to. A topic that shows up in both is your highest-confidence gap.

​
Workflow — turn a cluster into a published article

  1. Pick a cluster. Start at the top of the list — it is already sorted by miss count. Open the recent examples to confirm the questions really share an answer.
  2. Choose the target knowledge base. The header dropdown lists your knowledge bases; drafts land in the one you select. The dropdown’s state is explicit — loading, load-failed (with retry), and genuinely-empty are three different messages — and the draft button stays disabled until a base is chosen.
  3. Create the draft article. Click Create draft article on a cluster. Orbit drafts an answer card from the cluster’s real customer questions — the title seeded by the suggested topic, the body built from what customers actually asked — and uploads it into the selected knowledge base as a draft document. You are then deep-linked into that knowledge base to review it.
  4. Review and publish. A draft never grounds a live AI answer. Rewrite the body into the answer customers should receive, fill in the facts the drafter could not know (policies, windows, prices), then approve the document. Approval makes it retrievable by every agent attached to the base — the next customer who asks gets the answer instead of an escalation.
Over the API, the same step is one call:
The cluster_id is a stable hash of the cluster’s tokens — re-running the same window over the same data yields the same id. It is only valid inside the window you listed: change days, and the same cluster carries a different id. A days mismatch (or a window so old the cluster aged out) returns a 404 saying the cluster was not found in the selected window — re-list with the same days value and use the fresh id. days defaults to 30 when omitted. Promoting is a write action — it requires an owner, admin, or developer role, same as editing knowledge base content — and it never creates a knowledge base for you: which base a gap belongs to is a content organization decision only you can make. If the workspace has no knowledge base yet, create one first.

​
When the queue is empty

An empty list is one of two states, and the page text distinguishes them:
  • Complete coverage — misses arrived and the knowledge base answered every one. This is the goal state; nothing to do.
  • No deflection traffic yet — no agent ran deflection in the window. Widen the look-back dropdown first; if the list is still empty, attach a knowledge base to an agent and let inbound traffic flow. Misses start accumulating the first time a real question fails to match.
While the queue is empty, the sibling panel on the Knowledge base page still works — the agent-conversation signal picks up low-confidence assistant turns and escalations even when no deflection attempt was recorded — so a brand-new workspace can start mining gaps before the first deflection miss lands. Check the other signal when a cluster here seems thin; the gap you are looking for may be filed there.

​
See also