Structure
Categories contain folders, folders contain articles. Three levels of hierarchy is the working maximum — users almost never click past the second level when the in-page search is available. A typical commercial KB layout: Getting Started, How-To Guides, Troubleshooting, Reference, Release Notes, Policies. Avoid product-feature mirrors as your top-level categories — feature names change, user goals don’t. The folder layer below each category is where product-specific groupings live.
Multi-Portal
Freshdesk supports one default portal plus additional portals on Estate and Forest plans. The right pattern: a public KB per product line or per region (separate URL, separate branding, separate language fallback chain), and one internal KB visible only to logged-in agents for runbooks and escalation contacts. Articles can be republished across portals with portal-specific overrides for pricing, region-specific compliance language, or feature-availability notes. Portal switching is configured at Admin -> Channels -> Portals.
Article [Lifecycle
Stages](/articles/hubspot/hubspot-contact-lifecycle-stages/) are Draft, In Review, Published, and Archived. Set article-level expiration dates so the system flags stale content automatically — a 6-month TTL on troubleshooting articles and a 12-month TTL on policy articles is a reasonable default. The re-certification cycle: each article has an owner, the owner gets a reminder one week before expiration, and the article auto-moves to In Review status if not certified by the deadline. Without lifecycle, the KB becomes a landfill within 18 months and search relevance drops because top results contradict current product behavior.
// List articles past expiration via API
fetch(`https://${domain}.freshdesk.com/api/v2/solutions/articles?updated_since=2025-10-01T00:00:00Z`, {
headers: { Authorization: auth }
});Search
Suggested articles appear in the agent ticket UI (right sidebar matches against ticket subject and body) and on the customer-facing chat widget when Freddy Self Service is enabled. Relevance is tuned by feedback signals — thumbs up/down on articles, click-through from search results, time-on-page for logged-in users. The internal search index rebuilds nightly; new articles can take up to 24 hours to surface in agent suggestions. For urgent updates (a security advisory, a new pricing page), pin the article to the category top, which forces it into the top suggestions immediately.
Content Ops
Assign an owner per category — not per article, which doesn’t scale. Owners run weekly triage of feedback (every thumbs-down is a signal: bad article, missing article, or wrong reader expectation). Run a monthly content gap analysis from search misses (Admin -> Analytics -> KB -> Searches with no results); each line is a candidate for a new article. The discipline that separates a great KB from an average one is closing the gap loop within two weeks — not letting search misses queue up for a quarter.
Common Failure Modes
Three traps. First, importing a wiki dump and never restructuring — old wikis carry their own information architecture which is rarely the right one for a customer-facing KB. Plan the IA, then migrate, not the other way around. Second, no SEO on public articles — Freshdesk emits clean HTML but you still need unique titles and meta descriptions per article; the default title pattern is generic and crushes organic traffic. Third, no analytics tied to ticket deflection — KB success isn’t pageviews, it’s tickets-not-created; instrument by adding a “did this solve your problem?” widget and track the resolved rate.
What Changed in 2026
Freshdesk’s KB now ships native multilingual fallbacks so a customer requesting a Japanese article that doesn’t exist sees the English version with an inline “machine-translated” badge rather than a 404. The translation is on-the-fly and uses Freddy’s translation model. The badge can be styled per portal.
What to do this week
Pull the “search with no results” report for the last 30 days. The top 10 missing topics are your next 10 articles. Assign owners and dates today, draft within two weeks.
