Knowledge Base vs. Handbook

Atender ships two related-but-distinct content surfaces. They look similar — both have categories, both feed AI agents — but they serve different purposes. Use them both, but use them for different things.

Side by side

• Audience — Customers (public) and AI agents — Your team and AI agents (internal)
• Visibility — Published articles are public — Procedures are never shown to customers
• AI uses it for — Quoting answers, citing articles, deep-linking — Behavior shaping, escalation rules, internal logic
• Structure — Categories → Subcategories → Articles, plus Sections, Tags, Roles — Categories → Procedures only
• Statuses — draft, published, needs-review, archived — Visibility on/off
• Translations — Auto-translated into every active language — Not translated
• Custom domain — Served at your custom domain — No public surface
• Search — Public help-center search + AI retrieval — AI retrieval only
• Embeddings — Yes, hybrid retrieval (keyword + vector) — Yes, hybrid retrieval
• Roles — Browsing-visibility tags — Not used
• Access rules — None — articles are either public or private by status — Per-procedure or per-category, including a confidential flag and scope to specific agent configs
• Bulk actions — Status, move, archive — None — edit per procedure
• AI authoring — /api/kb/ai/write to draft a new article — None
• External API — /api/v1/kb/* with tenant API keys — Internal only — /api/handbook requires Supabase auth

When to write which

• A how-to a customer can follow themselves — Knowledge Base
• The team’s escalation tree — Handbook
• A product explainer — Knowledge Base
• The exact wording for offering a goodwill credit — Handbook
• A pricing FAQ — Knowledge Base
• The internal rule for who’s eligible for a discount — Handbook
• The instructions for cancelling a subscription — Knowledge Base (customer-facing) and Handbook (internal — what to confirm before cancelling)
• A guide for setting up the integration with your CRM — Knowledge Base
• The list of internal tools the support team uses — Handbook
• A “we are sorry your package was lost” template — Knowledge Base if it’s customer-facing wording; Handbook if it’s the internal protocol
• Refund policies — Both, but they look different. Customer-facing version in KB explains what’s eligible. Handbook version explains the internal approval flow.

A test you can use

Ask yourself: “Would I be comfortable if this exact text appeared in front of a customer, word for word?”

• Yes → it’s a Knowledge Base article. The customer-facing version goes there. The AI can quote it.
• No → it’s a Handbook procedure. Customer-facing AI agents read it for guidance but never expose it.

If the answer is “yes for some parts, no for others”, split them. The KB article is the part you can publish. The Handbook procedure adds the internal context the AI needs to act on it appropriately.

How both fit together

A typical customer-support flow uses both:

1. Customer asks a question on Web Chat.
2. The AI retrieves from the Knowledge Base — finds the relevant article, quotes it.
3. The AI also retrieves from the Handbook — finds the procedure for that scenario, reads it as guidance.
4. The AI’s response cites the KB article (the customer-facing answer) and behaves according to the Handbook procedure (escalation, tone, limits).

The customer sees a clean, quoted answer. Your team sees the procedures being applied consistently. The AI orchestrates both.

Common confusion

• “Should I tag KB articles for internal?” — No. If it’s internal, it goes in the Handbook, not the KB. Roles in the KB are for audience-aware browsing, not for hiding content from customers.
• “Can I link from a KB article to a Handbook procedure?” — Yes, the editor allows it, but customers can’t follow the link. Use Handbook links sparingly inside KB articles.
• “Can the AI quote a Handbook procedure?” — It shouldn’t. The Handbook informs behavior; it doesn’t supply quotes. If your AI starts quoting Handbook content to customers, the procedure is probably written too article-shaped — rewrite it as instructions.