Agents

How agents use your documents

An agent answers from what you gave it. It does not invent a price, a time or a policy, and every answer it can give is pinned to one immutable version you can read back, compare and roll back to.

Paths, field names, enum values, headers and error codes in these samples are the real ones, checked against the API's own specification when this page is built. The ids, amounts and names in them are illustrative. `$WETALK_API_KEY` and `$AGENT` are shell variables you set yourself.

A version is the unit, not the agent

Uploading a new document does not change the agent. It builds a new version. The old one keeps answering until the new one is published, so there is no window where the line is down or half-tailored. Every version records what it was built from, down to the SHA-256 of each file.

That is also the answer to "what did it say last March": versions are immutable and are not deleted, so the configuration behind any past conversation is still readable.

Versions and the documents behind one

curl https://api.wetalk.io/v1/agents/$AGENT/versions \
  -H "Authorization: Bearer $WETALK_API_KEY"

curl https://api.wetalk.io/v1/agents/$AGENT/versions/$VERSION/documents \
  -H "Authorization: Bearer $WETALK_API_KEY"

One document row

{
  "agent_document_id": "0199f1c2-6b43-7e25-8f66-4b2c7d5e0f43",
  "kind": "upload",
  "filename": "menu-autumn.pdf",
  "content_type": "application/pdf",
  "byte_size": 184320,
  "sha256": "9f2a4c8e1b7d3a6f0c5e9b2d8a4f7c1e3b6d9a2f5c8e1b4d7a0f3c6e9b2d5a8f",
  "uploaded_at": "2026-09-14T08:12:44Z"
}

Publishing and going back

Publish and restore are the same operation with the same guarantee. Both take `expected_live_version_seq` — the sequence you last read — and both refuse with `409 live_version_seq_stale` when it no longer matches. Two people cannot silently overwrite each other, and a rollback made from a stale screen is refused rather than applied to the wrong version.

Conversations already in flight are pinned. They finish on the version they were answered on; only conversations that start after the publish see the new one.

POST /v1/agents/{voice_agent_id}/versions/{agent_version_id}/restore

curl https://api.wetalk.io/v1/agents/$AGENT/versions/$OLDER_VERSION/restore \
  -X POST \
  -H "Authorization: Bearer $WETALK_API_KEY"
  -H "Content-Type: application/json" \
  -d '{ "expected_live_version_seq": 7 }'

What it could not answer

When a caller asks something the documents do not cover, the agent says so and hands over or takes a message — it does not guess. The question is clustered with every other caller who asked something similar and listed as a gap, with one caller's actual words beside the count so you can judge the cluster.

Writing an answer queues it. It publishes nothing and builds nothing: the factory folds the answer into the next version, and until that version is live the agent still cannot answer the question. The gap's `state` tells you which of the four stages it is at.

open — asked, not yet answered.
queued — an answer is written and waiting for the next build.
folded — the answer is in a published version and the agent now gives it.
dismissed — not worth answering.

POST /v1/agents/{voice_agent_id}/gaps/{gap_id}/answer

curl https://api.wetalk.io/v1/agents/$AGENT/gaps/$GAP/answer \
  -X POST \
  -H "Authorization: Bearer $WETALK_API_KEY"
  -H "Content-Type: application/json" \
  -d '{
    "answer_text": "We deliver to the old town and to Kifissia, nowhere further."
  }'

Languages

Pick the languages you serve when you create the agent. It greets in the first one and follows the caller when they switch, mid-sentence if necessary, and one voice speaks them all.

A language is a data pack, not code, and an incomplete pack makes that language unavailable — there is no English fallback anywhere in the platform. Asking for one is refused up front with `language_unavailable` or `language_pack_incomplete`, and `GET /v1/languages` is the list that is actually true today. Twenty-six languages is what WeTalk has committed to at launch, not what it speaks this morning.

Reading a conversation back

Conversations are cursor-paginated and filtered by query parameter, so a filtered view is a link somebody can paste into a message. The figures that come back describe the whole filtered set rather than the page, so they do not change as you scroll. Paging is never by offset: a conversation ending mid-page would otherwise duplicate a row or skip one.

One conversation carries its transcript, its event timeline and a reference to its recording. Listening to the recording is a separate, audited request: `POST /v1/conversations/{conversation_id}/recording/access` writes the audit entry first and then returns a short-lived URL.

GET /v1/conversations

curl -G https://api.wetalk.io/v1/conversations \
  -H "Authorization: Bearer $WETALK_API_KEY"
  --data-urlencode "voice_agent_id=$AGENT" \
  --data-urlencode "since=2026-09-01T00:00:00Z" \
  --data-urlencode "limit=50"

Paging with the cursor you were given

curl -G https://api.wetalk.io/v1/conversations \
  -H "Authorization: Bearer $WETALK_API_KEY"
  --data-urlencode "cursor=$NEXT_CURSOR"