Login Get started

Knowledge Base Documents

Documents are how you train your Hay agent. Every piece of information you upload becomes knowledge your agent can use to answer customer questions accurately.

What Are Documents?#

Documents are your agent's knowledge base - everything from FAQs to policy manuals. When a customer asks a question, Hay searches through your documents to find relevant information and generates accurate responses.

Think of it like training a new employee by giving them all your company documentation.

Why Documents Matter#

With good documentation:

  • ✅ Agent answers accurately
  • ✅ Customers get consistent information
  • ✅ Resolution rate increases
  • ✅ Fewer escalations to humans

Without enough documentation:

  • ❌ Agent guesses or says "I don't know"
  • ❌ Inconsistent answers
  • ❌ More escalations
  • ❌ Frustrated customers

Uploading Documents#

Step 1: Go to Documents#

  1. Click Documents in the left sidebar
  2. Click Import Documents

Step 2: Choose Your Method#

Upload Files

  • Drag and drop files
  • Click to browse and select
  • Upload multiple files at once

Supported formats:

  • PDF documents
  • Word documents (.doc, .docx)
  • Text files (.txt)
  • Markdown files (.md)
  • CSV files (for data)
  • HTML files (.html)
  • PowerPoint presentations (.ppt, .pptx)
  • JSON files (.json)

File size limit: The maximum upload size is 10 MB per file (configurable via the UPLOAD_MAX_SIZE_MB environment variable).

Write a document from scratch: To compose a document directly in Hay without uploading a file, go to /documents/new and use the Write Document editor.

Import from URL

  • Paste a website URL and Hay will crawl the entire site — it follows the sitemap and discovers same-domain pages automatically
  • Useful for importing an existing help center or documentation site
  • All discovered pages are processed and added as separate documents

Step 3: Processing#

Hay processes your documents:

  1. Extracts text and content
  2. Breaks into searchable chunks
  3. Creates smart connections
  4. Makes it instantly available

Usually takes: 5-30 seconds depending on size

Step 4: Review and Organize#

After upload:

  • Give document a clear title
  • Add a description (what information does it contain?)
  • Select a category from the dropdown: product, api, faq, legal, training, technical, or other
  • Set the document status: Draft, Published, or Archived. Hay also sets a document to Processing while it's being ingested, or Error if ingestion fails — these two are system-managed and not chosen manually.
  • Click Save

Types of Documents to Upload#

1. FAQs (Most Important!)#

Your frequently asked questions are gold.

Example:

Q: How long does shipping take?
A: Standard shipping takes 5-7 business days.
Express shipping takes 2-3 business days.

Q: What's your return policy?
A: We accept returns within 30 days of purchase.
Items must be unused and in original packaging.

Q: Do you ship internationally?
A: Yes, we ship to over 50 countries.
International shipping takes 10-14 business days.

2. Policies#

Upload your official policies:

  • Return and refund policy
  • Privacy policy
  • Shipping policy
  • Terms of service
  • Warranty information

3. Product Information#

Help customers learn about your products:

  • Product descriptions
  • Feature lists
  • Specifications
  • User manuals
  • Setup guides

4. Troubleshooting Guides#

Common issues and solutions:

  • Step-by-step fixes
  • Error messages and meanings
  • "How to" guides
  • Video transcripts

5. Process Documentation#

Internal processes that help answer questions:

  • How orders are processed
  • How refunds work
  • Account creation steps
  • Subscription management

6. Company Information#

Basic facts about your business:

  • Business hours
  • Contact information
  • Location/address
  • About us
  • Team information

Document Best Practices#

Writing for AI#

Your agent understands documents better when they're clear and structured.

✅ Do:

  • Use clear headings
  • Write complete sentences
  • Include context (who, what, when, where, why)
  • Use bullet points for lists
  • Define acronyms

❌ Don't:

  • Use vague references ("this", "that" without context)
  • Assume prior knowledge
  • Use internal codes without explanation
  • Leave information incomplete

Good Example:#

# Refund Policy

We offer full refunds within 30 days of purchase.

Eligibility:
- Item must be unused and in original condition
- Original packaging must be included
- Proof of purchase required (order number)

Process:
1. Customer requests refund
2. We provide return shipping label
3. Customer ships item back
4. Refund processed within 5-7 business days
5. Money returned to original payment method

Exceptions:
- Sale items: Store credit only
- Custom orders: No refunds
- Digital products: No refunds after download

Bad Example:#

Refunds: 30 days. See mgr for exceptions.

(Too vague, uses abbreviations, no helpful details)

Organizing Documents#

Use the category dropdown when uploading a document to keep your knowledge base organized:

  • faq - Frequently asked questions
  • product - Product descriptions and specs
  • api - API references and developer docs
  • legal - Terms of service, privacy policy, etc.
  • training - Internal training and onboarding content
  • technical - Troubleshooting guides and technical docs
  • other - Everything else

Keep Documents Updated#

Set reminders to review:

Monthly:

  • Check for outdated information
  • Add new FAQs from recent conversations
  • Update policies if changed

After Changes:

  • New products launched → Upload specs
  • Policy updated → Replace old version
  • New issues discovered → Add solutions

Managing Your Documents#

Viewing Documents#

Go to Documents to see all uploaded content.

What you'll see:

  • Name - Document title
  • Type - The document's content type (Article, Guide, FAQ, Tutorial, Reference, Policy)
  • Source - Where the document came from (upload, URL crawl, etc.)
  • Status - Draft, Published, Archived, Processing, or Error
  • Last Modified - When the document was last updated

Editing Documents#

To update existing document:

  1. Click on the document
  2. Click Edit
  3. Update content
  4. Click Save

Changes are reflected immediately.

Searching Documents#

Use the search bar to find specific documents:

  • Search by title
  • Search by content

Archiving Documents#

You can mark a document as Archived from the documents list without deleting it, using the archive action on each row or in bulk.

⚠️ Note: Archiving from the documents list is not yet fully functional — the action currently only updates what you see on screen and does not persist to the backend. Don't rely on it yet to keep a document out of use.

Deleting Documents#

To remove a document:

  1. Click on the document
  2. Click Delete
  3. Confirm

⚠️ Warning: Deleting is permanent. Agent will no longer have access to this information.

Advanced Features#

Document Sources#

Hay remembers where information comes from:

When the agent uses a document to answer a question, the conversation shows a document icon with "Agent is using a document to provide the answer" and a link to the source document's title, for example "Shipping Policy" or "Product Manual - Setup Guide". There are no page numbers — the citation points to the document itself.

This helps with:

  • Verifying accuracy
  • Finding outdated info
  • Tracking down errors

Common Scenarios#

"My agent gives wrong answers"#

Solutions:

  1. Check if information exists in documents
  2. If missing → Add the correct information
  3. If exists but wrong → Update the document
  4. If document is confusing → Rewrite more clearly

"Agent says 'I don't know' too often"#

Solutions:

  1. Identify what questions cause this
  2. Add documents covering those topics
  3. Make sure FAQs are comprehensive
  4. Include more context in documents

"Information is inconsistent"#

Solutions:

  1. Search for conflicting information
  2. Remove outdated documents
  3. Consolidate similar documents
  4. Keep one "source of truth" per topic

"Too many documents, hard to manage"#

Solutions:

  1. Consolidate similar documents
  2. Use clear naming convention
  3. Archive old/unused documents
  4. Use tags effectively

Document Checklist#

Before going live, make sure you have:

Essential Documents:

  • ☐ Top 20 FAQs
  • ☐ Shipping/delivery information
  • ☐ Return policy
  • ☐ Contact information
  • ☐ Business hours

Recommended Documents:

  • ☐ Product information
  • ☐ Troubleshooting guides
  • ☐ Account management help
  • ☐ Pricing information
  • ☐ Special promotions/policies

Nice to Have:

  • ☐ Company background
  • ☐ Detailed product specs
  • ☐ Advanced troubleshooting
  • ☐ Industry-specific information

Tips for Success#

Start Small#

Don't try to upload everything at once:

  1. Start with 10-20 most important FAQs
  2. Test your agent
  3. See what questions it struggles with
  4. Add more documentation to fill gaps

Quality Over Quantity#

Better to have 20 well-written, accurate documents than 200 poorly organized ones.

Use Customer Language#

Write documents in terms customers use:

  • ❌ "SKU lookup procedure"
  • ✅ "How to find your product number"

Include Examples#

When explaining processes, show examples:

To find your order number:
1. Check your confirmation email
2. Look for "Order #12345" near the top
3. It's always 5 digits starting with #

Test Your Documentation#

After uploading:

  1. Go to Playground
  2. Ask questions as a customer would
  3. See if answers are accurate
  4. Adjust documents as needed

Common Questions#

How many documents should I have?#

Start with 15-25 core documents. Add more as you discover gaps. Most successful setups have 50-150 documents.

Can documents be in different languages?#

Yes! Upload documents in the languages you support. Hay can understand and respond in multiple languages.

How long does it take for documents to be available?#

Usually 5-30 seconds after upload. Large documents may take up to a minute.

Can I upload confidential documents?#

Hay keeps all documents secure and private to your organization. However, only upload information you're comfortable your AI agent sharing with customers.

What if my document contains errors?#

Simply edit or re-upload the correct version. The agent will use the updated information immediately.

Next Steps#

Last updated July 13, 2026

View on GitHub
Previous
Playbooks
Next
Integrations