Give your AI phone agent a knowledge base

A knowledge base is what an agent knows about your business. It has three parts:

Field	What goes in it
`basic_info`	What you do, who for, where you are, opening hours, how to reach you
`faqs`	Questions callers ask, each with the answer to give
`other_info`	Prices, policies, how booking works, anything else

It can also hold files: price lists, menus, manuals and policies that are too long for those fields. The agent searches them during a call. An agent uses one knowledge base, set with knowledge_base_id. Several agents can share the same one. The agent’s mascot answers from it too, on the share link and the website widget. The console does all of this under Knowledge, at voice.wixzel.com/knowledge.

Write one by hand

curl https://api.voice.wixzel.com/v1/knowledge-bases \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smile Dental",
    "basic_info": "A family dental clinic in Kochi. Open Monday to Saturday, 9 am to 6 pm.",
    "faqs": [{ "question": "Do you take walk-ins?", "answer": "Yes, until 5 pm." }],
    "other_info": "A cleaning costs ₹800."
  }'

Draft one from a website

POST /v1/knowledge-bases/import reads a website, its home page and up to three pages it links to, and answers with a draft. Nothing is saved. Check the draft, fix anything that is wrong, then create it with the same fields:

curl https://api.voice.wixzel.com/v1/knowledge-bases/import \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }'

{
  "object": "knowledge_base_draft",
  "name": "Smile Dental",
  "description": "Imported from example.com.",
  "basic_info": "A family dental clinic in Kochi…",
  "faqs": [{ "question": "Do you take walk-ins?", "answer": "Yes, until 5 pm." }],
  "other_info": "A cleaning costs ₹800.",
  "source_url": "https://example.com"
}

Pass source_url along when you create it, so the console can show where it came from and read the site again later. Importing takes 10 to 60 seconds and is not charged. Each account can import 5 websites, then one a minute. A website that cannot be reached answers 422 website_unreadable; one with nothing to learn from answers 422 nothing_to_learn.

Draft one from a document

POST /v1/knowledge-bases/import-file does the same for one document: PDF, DOCX, TXT, MD, CSV or HTML, up to 10 MB. Upload it as multipart file, or send JSON { "url": "..." } to fetch it. Nothing is saved, and the answer is a draft like the one above, with source_url null.

curl https://api.voice.wixzel.com/v1/knowledge-bases/import-file \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -F "file=@about-us.pdf"

A draft keeps the short facts. To let the agent use all of a long document, add it as a file instead.

Files

Add documents to a knowledge base, and every agent using it can search them during calls. The agent does not read them in full on every reply: when a caller asks something the three fields do not cover, it calls its built-in search_knowledge tool, gets the few passages that match best, and answers from those.

curl https://api.voice.wixzel.com/v1/knowledge-bases/KB_ID/files \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -F "files=@menu.pdf" \
  -F "files=@price-list.docx"

Or fetch one from a public link:

curl https://api.voice.wixzel.com/v1/knowledge-bases/KB_ID/files \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/menu.pdf" }'

Each file comes back processing. Reading it takes a few seconds, then it is ready, with its pages and the number of passages (chunks) the agent can search. A file that cannot be read is failed, with the reason in error.

{
  "object": "knowledge_file",
  "id": "6720...",
  "knowledge_base_id": "671f...",
  "name": "menu.pdf",
  "kind": "pdf",
  "bytes": 182044,
  "pages": 4,
  "chars": 9120,
  "chunks": 12,
  "status": "ready",
  "error": null,
  "source_url": null,
  "created_at": "2026-10-20T09:30:00.000Z"
}

Route	Does
`GET /v1/knowledge-bases/{id}/files`	The files, newest first
`POST /v1/knowledge-bases/{id}/files`	Add up to 5 as multipart `files`, or one as JSON `{ url, name? }`
`GET /v1/knowledge-bases/{id}/files/{fileId}`	One file’s status
`DELETE /v1/knowledge-bases/{id}/files/{fileId}`	Remove it and what the agent could find in it

PDF, DOCX, TXT, MD, CSV and HTML, up to 10 MB each, 20 files per knowledge base.
Scanned PDFs, with no text in them, are read as images.
Only the text is kept, cut into passages. The file itself is not stored, so there is nothing to download again.
Deleting the knowledge base deletes its files.

Searches show on the call record as tool_calls of type knowledge, with the question the agent asked.

Give it to an agent

curl -X PATCH https://api.voice.wixzel.com/v1/agents/AGENT_ID \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "knowledge_base_id": "KB_ID" }'

Send "knowledge_base_id": null to take it away again. Deleting a knowledge base removes it from every agent that used it.

Agents made from a website

POST /v1/agents/generate with a website_url makes an agent and reads the site in the background. The agent gets a knowledge base drafted from the site, saved straight away. Edit it afterwards like any other.

curl https://api.voice.wixzel.com/v1/agents/generate \
  -H "Authorization: Bearer $WIXZEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "website_url": "https://example.com", "role": "receptionist" }'

A new look for an agent’s mascot, with POST /v1/agents/{id}/mascot/generate and a website_url, keeps the agent’s knowledge base as it is: the website only sets the look. Send "refresh_knowledge": true to rewrite the knowledge base from the website instead. That also changes what the agent says on phone calls. If the agent has no knowledge base, one is made from the website and given to it. See Mascots.

Keep it short

The three fields are read on every reply, not searched, so their length adds time to each answer. Keep them to what callers ask about most. Up to about 8,000 characters stays quick; past 20,000 replies get noticeably slower. Put anything longer in files, which cost nothing until the agent searches them.

Getting started

Guides

Carriers

Concepts

API reference

Give your AI phone agent a knowledge base

Write one by hand

Draft one from a website

Draft one from a document

Files

Give it to an agent

Agents made from a website

Keep it short

​Write one by hand

​Draft one from a website

​Draft one from a document

​Files

​Give it to an agent

​Agents made from a website

​Keep it short

Write one by hand

Draft one from a website

Draft one from a document

Files

Give it to an agent

Agents made from a website

Keep it short