Build

Knowledge

Give an agent your documents and it answers callers from them: a price list, a refund policy, opening hours, an FAQ. Without them an agent knows only what its instructions say.

Add a document

In the studio, open an agent and go to Knowledge. By API, a file is sent as the request body itself, with its name in the address:

Upload a file

curl -X POST "https://goblins-call-api.onrender.com/v1/knowledge/documents?name=Price%20list.pdf" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @"Price list.pdf"

Text you already have as a string is sent as JSON instead:

curl -X POST "https://goblins-call-api.onrender.com/v1/knowledge/documents" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Refund policy",
  "text": "A refund for a cancelled order is paid within seven working days to the card that was used."
}'

Either way the answer comes back at once with the document processing. It is read in the background and turns ready, or failed with a reason in error. Read it with Get a document to see which.

Accepted	Limit
PDF, Word (`.docx`), text (`.txt`, `.md`, `.csv`)	25 MB a file
Pasted text	200,000 characters
Documents in a workspace	500

Switch it on for an agent

A document belongs to your workspace, and each agent names the ones it answers from. In the studio that is the switch beside the document; by API it is the agent’s documentIds.

curl -X PATCH "https://goblins-call-api.onrender.com/v1/agents/ua_3f9a1c2b" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "documentIds": [
    "kd_4b1f0c9d2e7a6f53"
  ]
}'

What happens on a call

What the agent does with its documents depends on how much there is.

Documents add up to	On a call
About 6,000 characters (three pages) or less	They are written into the agent’s instructions, so every reply has them.
More than that	The agent is told what each document covers and looks a fact up when a caller asks for one. It says a short holding line while it does.

When a lookup finds nothing, the agent tells the caller it does not have that information. It is told never to guess a fact about your company.

Try a question first

Search documents returns what an agent with those documents would be handed for a question, with how closely each result matched. The studio’s Knowledge tab has the same thing as a box. Try the questions your callers really ask, in the language they ask them in.

curl -X POST "https://goblins-call-api.onrender.com/v1/knowledge/search" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "documentIds": [
    "kd_4b1f0c9d2e7a6f53"
  ],
  "query": "How long does a refund take?"
}'

Documents that work well

Write facts as sentences. “A first consultation costs five hundred rupees” is found and read out more reliably than a cell in a table.
Give each subject a heading. A heading stays attached to the passage under it.
Keep one subject to one document where you can, and delete documents that are out of date: an old price is still a price to the agent.
Questions and answers, written out, work best of all.

Who can read them

A lookup searches only the documents of the agent that is on the call, inside your workspace. The uploaded file is encrypted before it is stored. Bear in mind that anything in a document you switch on may be said to a caller: do not upload what callers should not hear.