Knowledge Base

Overview

The knowledge base lets you provide your assistant with specific information about your business. Instead of relying solely on the AI model's general knowledge, your assistant can reference your documentation, FAQs, product catalogs, and policies to give accurate, relevant answers.

For the full API reference, see api.happ.tools/reference.

Knowledge Types

URL

Import content from a web page:

1. Go to your assistant's Knowledge tab
2. Click Add Knowledge > URL
3. Paste the URL of the page to import
4. Enter a name and optional description
5. Click Save

Happ crawls the page and extracts its content for the assistant.

Best for: Documentation pages, FAQ pages, product catalogs, blog posts.

Text

Add content directly:

1. Click Add Knowledge > Text
2. Enter a name
3. Paste or type the content
4. Click Save

Best for: Company policies, FAQs, specific instructions, frequently referenced info.

File Upload

Upload documents:

1. Click Add Knowledge > File
2. Upload your document
3. Enter a name and optional description
4. Click Save

Supported formats and limits:

Via API

POST /api/assistant-knowledge
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "assistantId": "your-assistant-uuid",
  "name": "Company FAQ",
  "type": "text",
  "resourceContent": "Your FAQ content here..."
}

For file uploads, use Content-Type: multipart/form-data.

How It Works

1. Upload — Documents are stored securely
2. Processing — Text is extracted and split into chunks
3. Embedding — Chunks are converted to vector embeddings (using OpenAI text-embedding-3-large)
4. Search — When a user asks a question, the system finds the most relevant chunks
5. Response — The assistant uses the retrieved context to generate an accurate answer

Two Types of Knowledge Retrieval

Direct Knowledge (Non-Vector)

For smaller knowledge items, the content is appended directly to the assistant's system prompt. The AI sees the full text on every message.

Best for: Short content (FAQs, business hours, policies) where everything is always relevant.

Vector Search

For large knowledge bases, Happ uses vector search powered by Qdrant. This finds the most semantically relevant information for each question.

How vector search works:

1. The user's question is converted to a vector embedding
2. The system searches the vector database for the closest matches
3. A dynamic score threshold filters results (75% of best score, minimum 0.32)
4. The top 3 most relevant chunks are passed to the AI as context

Enabling vector search requires a Qdrant integration:

1. Go to Integrations > Add Integration > Qdrant
2. Enter your Qdrant API URL and API key
3. Specify a collection name
4. Toggle Vector on when creating knowledge entries

Best for: Large document collections where only specific sections are relevant per question.

Built-in searchKnowledge Tool

When your assistant has vector knowledge, a built-in searchKnowledge tool is automatically available. The AI calls it when it needs to look up information, searching with a query and receiving up to 3 relevant results.

Managing Knowledge

Listing

GET /api/assistant-knowledge?assistantId={assistantId}
X-Access-Token: happ_your_token_here

Updating

Click any knowledge entry to update its content, name, or description.

Deleting

DELETE /api/assistant-knowledge/{knowledgeId}
X-Access-Token: happ_your_token_here

Best Practices

1. Be specific — Include exact details (prices, hours, addresses) rather than vague descriptions
2. Keep it current — Update knowledge when your business information changes
3. Structure content — Use clear headings and bullet points for better retrieval
4. Use direct knowledge for essentials — Business hours, policies, and key info should be non-vector so the AI always sees them
5. Use vector search for large docs — Product catalogs, manuals, and FAQ collections work best as vector knowledge
6. Test thoroughly — Ask your assistant questions to verify it retrieves the right information