Knowledge Base
The knowledge base is everything factual your bot can look up — articles, scraped websites, and uploaded documents. The bot never memorizes it; it searches on demand with the searchKnowledgeBase tool, which is available automatically as soon as there is anything to search.
The knowledge base is your bot's reference material: return policies, shipping times, sizing guidance, warranty terms — every fact it might need but doesn't need to be thinking about all the time.
It is built from three sources — articles you write, websites you scrape, and documents you upload — and all of them end up in the same searchable pool.
This page builds on the Bot Operating Model. The one idea to carry in from there: the bot does not know your knowledge base. It searches it.
The bot searches; it does not memorize
Your knowledge base is never written into the bot's system prompt. What the bot gets instead is:
- A one-line note that a knowledge base exists and roughly how much content is in it.
- A single tool,
searchKnowledgeBase, that takes a search query and returns the matching passages.
When a customer asks something factual, the bot writes a search query, reads what comes back, and answers from it — the same way a support agent would search a help center rather than reciting it from memory. If it needs more, it searches again. There's no limit on how many times it can search within a conversation.
This has a direct consequence worth internalizing:
The bot is only as good as what it can find. If the answer isn't in the knowledge base, searching won't invent it. And if the answer is in there but phrased so differently from how customers ask that the search doesn't surface it, the bot effectively doesn't have it either.
It turns on by itself
searchKnowledgeBase is not something you enable, and it is not tied to a workflow.
Unlike custom actions, which only become available once a workflow that declares them is in play, searchKnowledgeBase is always available to the bot. The only condition is that there is something to search:
| Knowledge base state | What the bot gets |
|---|---|
| At least one active entry — article, webpage, or document | The tool and the knowledge base note, from the first message |
| Completely empty (or everything inactive) | Neither. The tool doesn't exist for the bot at all |
So a brand-new bot with one article can already look it up, with no workflow, no rule, and no configuration. Equally, if your knowledge base is empty, no amount of instructing the bot to "check the knowledge base" will do anything — there is no tool for it to call.
Where knowledge comes from
All three sources live under Settings → Knowledge for the business.
Articles
The primary source, and the one you'll use most. An article is a titled, markdown-formatted entry you write yourself in the Article Center. Best for anything you want deliberate control over — policies, procedures, canonical answers to common questions.
Articles support version history, archive and restore, categories, and JSON import/export for bulk editing.
If you have Zendesk connected, its Help Center articles can be synced in and become ordinary articles here, marked with their source. The same applies to other synced sources — once imported, they behave like any other article.
Websites
Point Octocom at a URL or a sitemap and it scrapes the pages into the knowledge base. Sitemap mode gives you a preview of the URL tree plus include and exclude patterns (wildcards supported), so you can pull in /help/* without dragging in your entire blog. Sitemaps are re-checked on a schedule; single pages can be rescraped on demand.
Good for a help center or documentation site you already maintain elsewhere. Less good as your only source — scraped marketing pages tend to be verbose and vague, which makes for poor search results.
Documents
Upload files directly. Accepted formats: .pdf, .docx, .txt, .md, .csv, .xlsx, .xls.
Text documents become one knowledge base entry with their extracted text. Spreadsheets and CSVs are handled row by row — each row becomes its own entry, which makes them a natural fit for structured reference data like a store list, a size chart, or a table of shipping rates per country.
After upload, the file needs to be processed before the bot can find it. The documents table shows a Learned percentage while that happens; it's usually seconds, longer for large PDFs.
How search actually works
Worth understanding, because it explains most "why didn't the bot find it?" situations.
Everything is chunked. Content isn't stored as whole articles but as passages. Anything up to about 6,000 characters stays as a single chunk. Longer content is split into 5,000-character windows that overlap by half, so a fact near a split point still appears whole in at least one chunk. For articles, the title is stored together with the body — so a clear, descriptive title genuinely helps the entry get found.
Search is by meaning, not keywords. The bot's query is compared against every chunk by semantic similarity, so a customer asking "can I send this back?" can match an article titled "Return policy" with no shared words.
Results are filtered before they reach the bot. The most similar chunks are gathered as candidates, then a language model reviews them against the query and keeps only the ones that actually answer it. The bot receives a focused set of passages, not a pile of loose matches, and there's a hard cap on the total volume returned per search.
Controlling what the bot can see
Articles have per-entry controls, in the Advanced Settings section of the article editor:
| Control | What it does |
|---|---|
| Active | When off, the article is invisible to the bot. It still exists and stays editable — this is the switch to reach for when an answer is temporarily wrong |
| Active From / Active To | An optional date window. Outside it, the article is invisible to the bot. Useful for seasonal policies — extended holiday returns, a promotion's terms, planned closures |
| Channels | Restricts the article to specific channels. Leave it empty and the article applies everywhere — that's the default |
Channel scoping is the tool for facts that are true on one channel and wrong on another: a phone bot shouldn't read out a long URL, and a web chat bot shouldn't quote phone-queue wait times.
These controls exist for articles only. Scraped webpages and uploaded documents are always active on every channel. If a fact needs scheduling or channel-scoping, it belongs in an article.
Websites and documents can, of course, be deleted — and archived articles are excluded from search while remaining restorable.
Help center visibility is a separate thing
An article can also be marked Public, which publishes it to your customer-facing help center. That is independent of whether the bot can use it: an article is available to the bot based on its Active state, not its Public state. Most articles are bot-only. Marking one public is an additional, deliberate step — internal escalation criteria or margin thresholds should stay private.
Writing knowledge the bot can actually find
The knowledge base is a search index, and content that reads well to a human isn't automatically content that retrieves well. A few habits that make a large difference:
Write in the customer's words, not your internal ones. An article titled "RMA Process — Tier 2" won't match "I want to return my order." Titles and opening sentences should read like the question a customer would ask.
One topic per article. A single sprawling "Policies" article gets chunked arbitrarily, and a search for shipping times may surface the chunk about warranty claims. Separate articles retrieve far more precisely.
Make each article self-contained. The bot may see one chunk with no surrounding context. "As mentioned above, this also applies here" is meaningless in isolation. Repeat the necessary context rather than referring to it.
State facts plainly. "Returns are accepted within 30 days of delivery, provided the item is unworn and in original packaging" is usable. "We aim to be flexible about returns wherever possible" gives the bot nothing to answer with, and it will either hedge or hand off.
Cover the phrasings customers actually use. If people ask about "refunds," "money back," and "cancelling an order" for the same underlying policy, mention those terms in the article. Semantic search is good, but it isn't telepathic.
Articles are searched in the language they're written in. If you maintain translations for your help center, the bot still searches the original article text and answers the customer in their own language. You do not need a translated copy of every article for the bot to work multilingually.
When to use the knowledge base — and when not to
The knowledge base is one of three places behavior and knowledge can live, and picking the right one matters more than how well you write any individual entry.
| What you're adding | Where it belongs |
|---|---|
| A fact the bot needs only when it's relevant | Knowledge base |
| A procedure for a specific situation, especially one that takes actions | A workflow |
| A global constraint that must hold in every conversation | A bot rule |
The knowledge base is where the vast majority of your content should go. It costs the bot nothing when it isn't relevant, and there's no practical limit on how much of it you can have — unlike bot rules, which are deliberately capped because they occupy the system prompt on every single turn.
One boundary worth being explicit about: the knowledge base is read-only reference material. It tells the bot things. It cannot make the bot do things. An article that says "when a customer asks for a refund, issue it" will not cause a refund — the bot has no refund tool unless a workflow gives it one. Anything involving an action belongs in a workflow.
Troubleshooting: the bot didn't find the answer
Work down this list:
- Is the entry active? Check the Active toggle and, if set, the active period. An expired Active To date silently removes the article from search.
- Is it channel-scoped? An article restricted to web chat is invisible to your email bot.
- Has it finished processing? Freshly uploaded documents and newly scraped pages take a moment to become searchable. Check the Learned column.
- Would you find it by searching? Read the customer's message, imagine the search phrase the bot would write, and ask whether your article's title and opening line resemble it. This is the most common cause by far — the content is there, phrased in internal language.
- Is it buried in a long article? A fact three thousand words into a general article competes with everything around it. Split it out.
- Is it actually a workflow problem? If the bot found the right information but did the wrong thing with it, that's not a knowledge base gap. See workflows.
You can see exactly what the bot searched for and what came back in the conversation's debug view — every searchKnowledgeBase call is logged with its query and how many passages it returned, which usually settles the question immediately.