In-Product Help Center & Knowledge Base — Chat Prompts

⬅️ Back to 6. Grow

If you're a B2B SaaS in 2026 and your support volume is climbing while your product surface keeps expanding, you'll hit the moment when "email us at help@" plus a Notion knowledge base no longer cuts it. Customers ask the same questions; reps repeat the same answers; documentation drifts out of date because it lives in a separate tool nobody updates. The right shape: an in-product help center that surfaces relevant docs at the point of need, supports self-serve troubleshooting, integrates AI for natural-language search + summarization, and routes to human support cleanly when self-serve fails.

The naive shape: link to your help docs in the footer. Customers click; bounce out of your product to a separate site; lose context; usually email you anyway. The right shape: searchable knowledge base accessible from a "?" button anywhere in your app, with contextual surfacing (showing relevant articles based on what the user is doing), AI-powered Q&A, and a clean handoff to live chat / ticket creation if the article doesn't solve the problem.

This chat walks through implementing a real in-product help center: content management, search architecture, AI-powered answers, contextual surfacing, escalation flow, analytics, and the operational realities of keeping docs fresh.

What you're building

A knowledge base content management system (CMS for support docs)
A help-center widget accessible from anywhere in your app
Search (full-text + semantic)
AI-powered Q&A on your docs (RAG over your docs)
Contextual surfacing (suggest articles based on current page / action)
Escalation flow: didn't help → contact support
Analytics: which articles work, which don't
Operational discipline: doc freshness; deflection rate; support team feedback loop

1. Decide the scope BEFORE building

Help me decide what shape of help center to ship.

Three increasingly-deep shapes:

LEVEL 1: STATIC HELP CENTER (the simplest start)
- Help docs hosted on a CMS (Intercom, Zendesk Guide, your own static site)
- Linked from in-product "Help" link
- Linked from emails
- Search exists; basic
- Pros: ships in 2-4 weeks; off-the-shelf vendors
- Cons: separate from product; loses context

LEVEL 2: IN-PRODUCT HELP WIDGET (modal / sidebar in app)
- "?" button in product header
- Opens overlay/sidebar with searchable knowledge base
- Customer never leaves your product
- Some contextual hints (e.g. "viewing settings? here are settings articles")
- Pros: contextual; product-integrated
- Cons: more engineering; need to integrate widget

LEVEL 3: AI-POWERED HELP CENTER
- All Level 2 features
- Plus: AI answers questions in natural language
- RAG over your docs + product context
- Cites sources from KB
- Falls back to ticket creation if AI uncertain
- Pros: dramatic deflection (60-80%+ vs 30% for static)
- Cons: ongoing engineering; eval discipline; AI cost

DEFAULT FOR MOST B2B SaaS:
- Year 1-2: Level 1 (Intercom Articles, Zendesk Guide, GitBook, or Mintlify; whichever fits)
- Year 2+: Level 2 (in-product widget) when support volume justifies engineering investment
- Year 3+: Level 3 (AI-powered) — actually achievable cost-wise in 2026

Don't pre-build Level 3. Customers want help that works; AI alone doesn't ensure that.

Output: explicit scope decision; what's in v1 and what's not.

Output: scope statement; align team on what we're shipping.

2. Pick the CMS for your knowledge base

Where do support docs live?

Off-the-shelf CMS options:

1. Intercom Articles
- If you already use Intercom for live chat, this is bundled.
- Decent UX; integrates with Intercom Inbox.
- Per-article analytics (views, helpful votes).

2. Zendesk Guide
- If you're on Zendesk for support.
- Mature; enterprise-strong.

3. HelpScout Docs
- Good UX; pairs with HelpScout inbox.

4. GitBook
- Documentation-style; markdown-friendly.
- Good for technical / dev-tool products.

5. Mintlify
- Modern; developer-doc-style.
- API doc strong.
- Good for technical products.

6. Markprompt / inkeep / Kapa
- AI-first knowledge base tools (built-in semantic search + AI answers).
- Pairs with your existing docs.

7. Notion
- Engineering-team-friendly for small co; not customer-facing-polished.
- Often the starting point; migrate to dedicated tool when serious.

8. Custom-built (your own CMS)
- Full control; pairs natively with your product.
- More engineering; consider when the off-the-shelf options don't fit.

DEFAULT RECOMMENDATIONS:

For non-technical SaaS (HR / sales / marketing tools):
- Intercom Articles or HelpScout Docs (paired with their chat)

For developer tools / technical products:
- Mintlify or GitBook (developer-doc style)

For modern SaaS with serious engineering investment:
- Custom CMS over headless backend (Sanity, Contentful, MDX)
- Or off-the-shelf + AI layer (Markprompt / inkeep)

Don't:
- Build a custom CMS at <$5M ARR
- Use Notion as customer-facing docs (lacks search, branding, analytics)
- Use Wordpress for technical docs

Implement:
1. CMS choice + setup
2. Brand styling (your colors, fonts)
3. Initial content migration
4. Search configured
5. Analytics integration

Output: CMS picked + initial content live.

3. Design the help-widget UX

Now build the in-product help widget (Level 2).

Design specs:

Trigger:
- "?" button in app header (always visible)
- Optional: keyboard shortcut (Cmd+/, common pattern)
- Optional: contextual triggers ("Need help with this?" inline at certain UI elements)

Widget shape:
- Slide-in sidebar (right side; 380-420px wide)
- Or overlay modal (full-screen on mobile)
- Or floating chat-bubble bottom-right (Intercom-style)
- Pick ONE pattern; don't mix

Widget content:

Top:
- Search bar (always focused on open)
- Close button

Empty state (no search):
- Suggested articles based on:
  - Current page / route
  - Customer's segment / role
  - Recently-viewed articles
  - Most-popular articles
- Quick links to common actions: "Contact support", "What's new", "Status"

Search results:
- Inline results as user types (debounced 200ms)
- Article preview on hover (right pane)
- "Open in full view" option

Article view:
- Markdown rendered with custom components (videos, code blocks, callouts)
- Table of contents on right (for long articles)
- "Was this helpful?" thumbs at bottom
- Related articles
- "Still need help?" → escalation

Escalation:
- "Contact support" button → opens chat OR creates ticket
- Pre-fills with: page, error context, attempted solutions

Mobile:
- Full-screen overlay
- Touch-friendly
- Responsive

Performance:
- Lazy-load article content (don't ship all docs in widget bundle)
- Cache recently-viewed
- Search index hosted on edge (Algolia / Typesense)
- Cold-load <300ms; warm <100ms

Accessibility:
- Esc closes
- Trapped focus
- ARIA roles
- Screen-reader friendly

Implement:
1. Widget component (React / your framework)
2. CMS API integration (fetch articles)
3. Search (Algolia / Typesense / Postgres FTS / your existing search)
4. Routing (/help/[slug] for direct article URLs)
5. Mobile responsive
6. Analytics events
7. Keyboard shortcuts

Output: a help widget that loads fast and feels native.

4. Implement search architecture

Search is the most-used feature. Get it right.

Three layers of search:

Layer 1: Full-text search (lexical)
- Index article title + headings + body
- Use Algolia / Typesense / Meilisearch / Postgres FTS
- Fast (<50ms p95)
- Lexical match (exact / partial words)

Layer 2: Semantic search (embeddings)
- Embed each article (and ideally each section) with [text-embedding-3-large / cohere / voyage]
- Search query embedded; cosine-similarity match
- Captures meaning beyond keywords
- Pair with lexical via reranking

Layer 3: AI-powered Q&A (Level 3 RAG)
- User asks natural-language question
- Retrieve top-k relevant articles via Layer 1+2
- Pass to LLM with question; LLM synthesizes answer with citations
- Show: "Here's what I found" + cited articles + "Wasn't this helpful? Contact us"

Implementation order:
- v0: Layer 1 only (lexical search)
- v1: Add Layer 2 (semantic) for better recall
- v2: Add Layer 3 (AI Q&A) when basics are solid

Search index management:
- Re-index on article publish/update
- Webhook from CMS → re-index trigger
- Daily re-index full sweep (catches deletes, missed updates)

Sample search flow with Algolia:

import { algoliasearch } from 'algoliasearch'

const client = algoliasearch(APP_ID, SEARCH_KEY)
const index = client.initIndex('help_articles')

async function searchArticles(query: string) {
  const result = await index.search(query, {
    hitsPerPage: 10,
    attributesToHighlight: ['title', 'body'],
    snippetEllipsisText: '...',
  })
  return result.hits
}

For semantic + RAG:

import { embed } from 'ai'

async function semanticSearch(query: string) {
  const queryEmbedding = await embed({
    model: 'openai/text-embedding-3-large',
    value: query,
  })
  
  const articles = await db.helpArticles.cosine_similarity_search(queryEmbedding, { limit: 5 })
  return articles
}

async function aiAnswer(question: string) {
  const articles = await semanticSearch(question)
  const context = articles.map(a => `<article id="${a.id}">${a.body}</article>`).join('\n\n')
  
  const answer = await generateText({
    model: 'anthropic/claude-sonnet-4-7',
    system: `You answer questions about [Product] based on these help articles. 
             Cite article IDs in your answer like [1], [2]. 
             If the articles don't answer the question, say so clearly.`,
    prompt: `Articles:\n${context}\n\nQuestion: ${question}`,
  })
  
  return { answer, sources: articles }
}

Implement:
1. Lexical search (Algolia / Typesense)
2. Semantic search (embeddings + vector DB)
3. Hybrid reranking
4. AI Q&A endpoint
5. Citation rendering in UI
6. Re-indexing webhook
7. Search analytics (most-searched queries; zero-result queries)

Output: search that surfaces the right article 90%+ of the time.

5. Implement contextual surfacing

The biggest UX win: surfacing the RIGHT articles based on what the user is doing.

Context signals:

1. Current route / page
- /settings/billing → suggest "Billing FAQ"
- /workflows/new → suggest "Getting started with workflows"
- /api → suggest "API quick start"

2. User segment
- Free-tier user → suggest "Upgrading to Pro"
- Admin user → suggest admin-specific articles
- New user (within 7 days) → suggest onboarding articles

3. Recent actions
- Just hit a paywall? → suggest "Plan limits explained"
- Recent error? → suggest troubleshooting

4. Time-aware
- "Latest changes" articles for users who just logged in after extended absence

Implementation:

Per-route help mapping:

const routeHelp: Record<string, string[]> = {
  '/settings/billing': ['billing-faq', 'invoice-explanation', 'upgrade-downgrade'],
  '/integrations': ['integrations-overview', 'connect-slack'],
  '/api': ['api-quickstart', 'authentication', 'rate-limits'],
  // ...
}

In widget:

function HelpWidget() {
  const route = usePathname()
  const user = useUser()
  
  const suggestedSlugs = useMemo(() => {
    const fromRoute = routeHelp[route] ?? []
    const fromSegment = getSegmentArticles(user.segment)
    const fromRecent = user.recent_articles.slice(0, 3)
    return uniq([...fromRoute, ...fromSegment, ...fromRecent])
  }, [route, user])
  
  // Show suggestedSlugs in empty state of search
}

Avoid:
- Showing 20 suggestions (overwhelming)
- Suggesting irrelevant articles based on weak signals
- Surfacing same articles every page (suggests no personalization)

Implement:
1. Per-route help mapping (manage in code or CMS)
2. User-segment article tagging
3. Recent-article tracking
4. Empty-state rendering with suggestions
5. A/B test: with/without suggestions to validate value

Output: relevant articles in front of users without them searching.

6. AI-powered Q&A (Level 3)

The 2026 differentiator: AI that answers customer questions citing your docs.

Architecture (RAG over help docs):

1. User types question in widget
2. Embed question
3. Retrieve top-5 articles via semantic + lexical hybrid
4. Re-rank for relevance
5. Pass top-3 to LLM with question
6. LLM synthesizes answer with citations
7. Stream answer to UI
8. Show source articles linked
9. Footer: "Was this helpful?" + "Contact support if not"

Prompt structure:

system: |
  You are a helpful support agent for [Product].
  Answer ONLY based on the provided articles.
  If the articles don't fully answer, say "I'm not sure based on the articles I have. Let me connect you to support."
  Cite articles using [1], [2], etc.
  Be concise (under 200 words).
  Don't apologize; be direct.
  Don't make up features.

user: |
  Articles:
  [1] {title1}: {body1}
  [2] {title2}: {body2}
  [3] {title3}: {body3}
  
  Question: {user_question}

Streaming response:
- Token-by-token to UI (better UX; user sees progress)
- Use Vercel AI SDK with streamText

Confidence scoring:
- LLM-as-judge: rate confidence
- If low confidence (e.g., articles barely relevant): show "I'm not sure"
- Or: classify as "covered" vs "uncovered"; uncovered → human escalation

Hallucination prevention:
- Strict prompt: "ONLY cite from provided articles"
- Post-generation check: verify all claims have citations
- If hallucination detected: regenerate or escalate

Cost management:
- Cache common questions (most users ask similar things)
- Use cheaper model for retrieval (embedding); SOTA for synthesis (Claude Sonnet 4.7)
- Token budget per response (~500-1000 tokens)
- Per-user rate limit (e.g., 20 AI questions per session)

Evaluation:
- Curate golden test set: 50-100 representative questions + expected articles + acceptable answers
- Run nightly via Promptfoo / Braintrust
- Monitor regressions

Audit + feedback:
- Log every AI answer + citations + user feedback
- Weekly review: which questions did AI fail? Add docs / improve prompt / improve retrieval.

Implement:
1. The RAG pipeline (retrieval + generation)
2. Streaming UI for AI answers
3. Citation rendering with article links
4. "Was this helpful?" feedback capture
5. Confidence-based escalation
6. Cost controls per user
7. Eval harness for quality
8. Operational dashboards

Output: AI that genuinely deflects support tickets without lying.

7. Escalation flow (didn't help → human)

When self-serve fails, escalate cleanly. Don't make the customer start over.

Escalation triggers:
- Customer clicks "Contact support" in widget
- Customer rates an article unhelpful
- AI answers with low confidence
- Customer searches with no results
- Pattern detection: 3 articles viewed in 5 minutes → likely struggling

Escalation flow:

1. Capture context (auto):
- Current URL + user state
- Searches attempted
- Articles viewed
- AI answer (if any)
- Customer plan / segment
- Recent error events from app

2. Pre-fill ticket / chat:
- Subject suggested based on context
- Body pre-filled with: "I was on [page]; tried [search]; couldn't find answer."
- Customer can edit before sending

3. Route to right channel:
- High-tier customer / urgent → live chat
- Standard → ticket
- Free tier → community / forum
- Off-hours → ticket with response-time SLA shown

4. Acknowledge:
- "We received your question; reply within X hours"
- Show approximate wait time

5. Continuity:
- When support replies, ALSO update the help center if there's a doc gap

Implementation:

async function handleEscalation(context: HelpContext, message: string) {
  const ticket = await supportSystem.createTicket({
    subject: deriveSubject(context, message),
    body: message,
    metadata: {
      page: context.current_page,
      searches: context.recent_searches,
      articles_viewed: context.recent_articles,
      ai_answer: context.last_ai_answer,
      user_id: context.user_id,
      plan: context.user.plan,
    },
    priority: derivePriority(context.user.plan),
  })
  
  return ticket
}

Pre-fills are critical. A ticket with "support button clicked" is useless; a ticket with full context lets your team solve in one round-trip.

Implement:
1. Context capture in widget
2. Pre-fill logic
3. Routing rules (chat / ticket / community)
4. Acknowledgment UX
5. Doc-gap-feedback loop (support → docs)

Output: escalation that doesn't drop context.

8. Operational discipline (keeping docs fresh)

Help docs rot fast without discipline.

Doc-freshness practices:

1. Ownership
- Each article has a designated owner (PM, support lead, or eng lead)
- "Last reviewed" date visible on every article
- Articles older than 90 days flagged for review

2. Triggers for updates
- Product change → docs review checklist
- Customer support question pattern (5+ tickets on same topic) → write or update article
- Feature deprecation → update or archive related articles

3. Editorial cadence
- Weekly: support team flags "missing or outdated" articles
- Monthly: review top-search-no-result queries
- Quarterly: full content audit

4. Voice + style guide
- Consistent tone across articles
- Short sentences; second person; active voice
- Screenshots updated alongside features
- Canonical names (don't call it "the integration page" in one place and "the Connectors tab" in another)

5. Internationalization
- If supporting multiple languages: translation cadence
- Keep language versions in sync (English first; others lag by N weeks)

6. Feedback loop
- "Was this helpful?" rate < 50% → flag for review
- Comments / suggestions captured
- Support team reviews flagged articles weekly

7. Analytics-driven prioritization
- Most-viewed articles get most love
- Zero-search-result queries → write missing article
- Article with high view + low helpfulness → rewrite

Implement:
1. Owner field on every article
2. Last-reviewed timestamp + auto-flag UI
3. Support feedback loop (Slack channel; weekly review)
4. Editorial calendar
5. Analytics dashboard for content team
6. Style guide document

Output: docs that stay accurate.

9. Analytics + measurement

What you measure improves.

Help-center metrics:

Content-level:
- Article views
- "Was this helpful?" rate
- Time-on-page
- Bounce rate
- Search-CTR (search → click → article view)
- Articles after which user contacts support (signal of doc gap)

Search-level:
- Top queries
- Zero-result queries (these are doc gaps)
- Click-through rate from search

AI-level (if Level 3):
- AI questions per session
- AI helpful rate (thumbs up/down)
- AI cost per question
- Confidence distribution (% high / medium / low)
- Hallucination rate (sample audit)

Deflection metrics (the headline):
- Self-serve resolution rate (sessions ending without ticket creation)
- Ticket reduction over time
- Cost-per-ticket-deflected (revenue impact)

Per-customer-segment:
- Help usage by free vs paid
- Help usage by new vs tenured
- Most-helpful-article by persona

Implementation:

Capture events in [PostHog / Amplitude / your analytics]:

helpcenter.opened
helpcenter.searched (query, results_count)
helpcenter.article_viewed (slug, source: search/suggestion/ai)
helpcenter.helpful_rated (article, vote)
helpcenter.ai_question_asked
helpcenter.ai_answered (confidence, sources)
helpcenter.escalated_to_support (page, attempted, reason)

Dashboards:
- Top articles (engagement + helpfulness)
- Search performance (top queries + zero-results)
- AI quality
- Deflection over time

Run quarterly: "What's our deflection rate? Up or down?"

Implement:
1. Event instrumentation throughout widget
2. Dashboard in PostHog / Amplitude / Looker
3. Weekly metrics review (support team + product)
4. Quarterly deflection report to leadership

Output: instrumented help center that improves over time.

10. Edge cases + operational realities

Walk me through:

1. Customer in workspace without internet (rare but real)
- Help center fails gracefully; offer cached articles if PWA pattern
- Or: clear error + "use email contact"

2. Customer asks question in non-English
- Detect language; offer language switch
- Multi-language search; multi-language KB
- Or: machine-translate query + serve English; use bilingual model for AI answer

3. AI answer is wrong (hallucination)
- Customer flags via thumbs-down + comment
- Auto-create ticket for content team
- Investigate: was retrieval wrong? Was prompt wrong? Update.

4. Customer asks something not covered
- AI says "I don't know"
- Capture as "uncovered topic"
- Weekly review for doc creation

5. Customer wants to print / save article
- Print stylesheet
- Export as PDF
- Email-to-self function

6. Customer searches using product-internal jargon
- Add synonym mapping (Algolia synonyms; Typesense overrides)
- E.g., "deal" = "opportunity"; "assignment" = "task"

7. Customer-side admin wants to surface specific articles in their workspace
- Workspace-level featured articles
- Hide irrelevant articles based on plan / features

8. Article references deprecated feature
- Auto-flag on feature deprecation event (CI check)
- Schedule update or archive

9. SEO concern (public help center pages)
- Internal-product-help can be private
- Public help-docs SEO-optimized; canonicalized
- Sitemap with all public articles

10. Help articles changed; users confused
- "What changed" indicator
- Email notify for users who read old version (if subscribed)

11. Customer-data privacy (logged-in helped articles include their data)
- Don't include customer-specific data in shared articles
- Keep articles generic; product-context fills in

12. AI cost spike
- Per-customer rate limit
- Per-day cost cap
- Alert on anomalous usage

For each: code change + UX impact + ops consideration.

Output: ops that don't break.

11. Recap

What you've built:

What you're explicitly NOT shipping in v1:

Voice-based help (defer; expensive to build well)
Video tutorials embedded in help (separate workflow)
Customer-co-edit articles (anti-pattern; trust issue)
Personal help-center per customer (defer; usually unnecessary)
24/7 live AI agent (Level 3 is asynchronous; full agent is different scope)

Ship Level 1 + Level 2 in 6-10 weeks. Add Level 3 when content base is solid + AI eval discipline in place.

The biggest mistake teams make: shipping AI Q&A before the underlying docs are good. AI answers garbage when retrieving from garbage. Get docs to 80%-quality first.

The second mistake: not measuring deflection rate. If you don't know whether the help center is working, you can't improve it.

The third mistake: separating help docs from product. Customers won't context-switch out of your product. In-product matters.